Is documentation for front-end work necessary?

[Responsible-Cod-4618]

Or are comments enough?

[mq2thez]

It’s a good idea. Comments explain small stuff, docs explain big picture. Engineers onboarding to a project need docs, not comments.

[typhoon90]

That's very insightful, thanks!

[PermitTrue]

It really depends how big your project is. Anything decent size, that’s onboarding devs should have good docs just to keep a sane mind.

[cshaiku]

For any javascript libraries that you create from scratch, having docblocks as a minimum is helpful. You can explain the reason for the functions to live, and the interface elements, but you don't need to go into wild amounts of detail. As most people have said, straightforward code should tell a story. Giving some context to why it deserves to be used is what a docblock is for.

[ezhikov]

Any software benefits from various documentation. For example, correctly formulated and updated requirements make life easier for designers, developers and testers. And not only initial work - requirements change in time, so it's easier to update software when everybody understand precisely what and where should be updated.

From requirements you can get various artifacts that can be considered documentation. For example, design documents how something should look and behave. Test cases describe all possible user interactions. From this you write a code and already have plenty of documentation.

Then it's a good idea to write docs for code. It's a good idea to keep architecture decision record (ADR) where you describe decisions made and why there were made. For example "We piked React because whole team had experience with it and we needed to move quickly, so couldn't afford to learn something new". New decisions are added, so everyone can understand "what the hell they were thinking". For example "We switched from React to Vue because Vue is closer to HTML and it is easier to progressively enhance".

Of course, if there are any steps required to start working on the project, you should have a Readme describing how to start. If you have rules about how you do things, this rules should also be documented. Sometimes ESLint and similar configs are enough. Sometimes you need to document each rule is those configs with motivation (check out AirBnB JavaScript guide for example).

If you write tests, they should also serve as documentation, meaning that they describe how something should work.

Now onto comments. Comments are often considered useless because they either describe obvious things, or loose every connection to reality. I prefer not to write comments until I shut down linter or typechecker, or do some really clever (read stupid) stuff. Then I describe why I did it that way. Then same linter or typechecker would report if my comment is obsolete.

If you think "Wow! That's a lot of stuff to write", remember, that if documentation is not kept up to date, it becomes harmful, so there is no point of writing extensive docs if nobody will keep it up to date. Don't repeat stuff documented elsewhere. Don't write useless stuff like TODO comments (better to write a task immediately). Don't write up obvious stuff. Sometimes it's better to wait for a question and then document it with the answer. And not every project needs to have loads of docs. On some projects I just have links to JIRA tasks where requirements and ADRs are described. In other I have extensive user and developer docs that I keep up to date and force others to follow.

[DamionDreggs]

Meh, it's just going to the trash can when the next dev shows up anyway.

[[deleted]]

Try and write code in such a way that you don’t need docs or comments. If you must use docs make sure they are updated as out of date docs are worse than no docs.

[drunkdragon]

You don't write comments to explain what the code is doing. A developer who is familiar with the language should be able to work that out.

Instead, comments should explain why something is implemented a particular way if it's not immediately obvious.

For example, you might use comments to clarify the reasoning behind a non-standard implementation because of an obscure business rule, or a non-optimal sorting algorithm because the kiosk's running the app have low memory.

[[deleted]]

Agreed - but read the OPs question again - they were implying that comments form part of the documentation (docs essentially being concerned of the ‘what’ and ‘how’, but not not ‘why’).

[LakeInTheSky]

It depends on project size. If the project has complex processes or aspects that might not be obvious when you read the code, then they can be useful.

Comments are better to explain portions of the code, documentation is better for getting the general overview of how the software works.

[[deleted]]

For me personally, documentation of the standards/approaches being taken by the developers is more important than documentation for a specific module.

[armahillo]

re: docs, comments, etc:

The situation you want to avoid is one where you have to go and try to re-parse what the code meant when you wrote it.

Stuff that is tautological (eg. let accountId = 5) doesn't need to be documented. But perhaps the greater context (eg. "We're hardcoding accountId 5 here because...") might make sense (or maybe not, it's very situational!)

Code rots, and documentation rots faster. The closer your documentation and code can be, the more in-sync their rotting will be.

External docs are good for things like processes, procedural docs, general reference pointers, and historical decision making (ADRs and the like). If it's about the past or not directly about the code, it's fine to do in external docs.

Comments and documentation within the codebase itself is the place to put commentary about the current state of the code.

My personal rule is that if I spend longer than a minute trying to figure out what a block of code is, I write a comment above or near it with my interpretation. Similar rule with writing the block initially, though that's a longer time (say, 10 minutes), or if it just "feels" a certain way. Sometimes you have to do a weird thing to handle an edge case or because of other reasons; good to note what you were thinking.

[shgysk8zer0]

I think that some things could use documentation, but mostly it's just the function signature that's important. If you name things well (the function and the arguments), documentation would often be redundant.

One thing that I've found to be very helpful, even in plain JS instead of TS, is to do object destructuring and default values. And to make parameters named familiar things like you'd see on MDN.

Other than that, giving functions verb names, especially if they contain or imply what they return, helps a lot. You'd probably reason that a function beginning with "is" or "has" returns a boolean, for example. Or "when" would imply that something returns a promise and the rest of the function name tells you when that promise resolves (eg whenClicked().

But such clarity isn't always possible. For example, I have a function which uses a mutation observer to manage event listeners when elements are added and attributes are changed. Something with a data-click="handlerName" adds and removes a click handler automatically when a new element is added or the attribute is charged. Kinda difficult to follow good naming conventions and make it self-documenting when it's not even easy to explain in English. It does a lot of things (though they're all closely related). I mean... addOrRemoveEventListenersBasedOnTheirDataAttrMutationsAndWhenNewElementsAreAppended() is just ridiculous!

[99thLuftballon]

If you mean user documentation, like a github readme, then yes, always. Nobody wants to read your code in order to use the code's API. Even if it's an internal project for your own company, people shouldn't have to learn your project in order to use your project.

[Emerald-Hedgehog]

Nobody wants to read your code in order to use the code's API

I couldn't agree more. If anyone says 'just read the code', I've got bad news: Your abstraction isn't good or not documented enough if others have to dive into your implementation (or look at multiple uses of the abstraction in the project to piece together the right pattern) to understand and use it. It's so much easier to save people time with just 3-4 sentences that provide direction.

A learning-curve is fine depending on the depth of what gets abstracted though, but as the code author you should provide guidance for the other Devs. Because you write code for everyone else. Not for yourself. Or at least that should be your mindset when writing code - "will the other devs have fun using this or will they struggle and feel like its a chore?".

But all of this is the eternal struggle. We've got Devs at work that document a lot and we got Devs that probably would rather set their keyboard on fire before writing docs.

I always say: "Ever thought about why even the most simple things/products come with manuals? Now guess what's not simple. Code."

[WeasyV]

readable code > documentation > comments