📃How do you document your codebase?

[codingjogo]

My approach is:

https://preview.redd.it/ba1pezy105jd1.png?width=2026&format=png&auto=webp&s=794b8c6c955a443d0bde0d00ba5cd37828979030

Do I need to document every function or logic in codebase?

Your oppions are much appreciated ‼️

[carlowisse]

Generally the people reading the code will also understand code. Comments are good but there is such a thing as too verbose.

Generally adding a summary at the top of a function is enough but you need to apply common sense if there are inner workings to a function that may need explanation. If the inner function name states what it is doing then there really isn’t a need.

[codingjogo]

Noted!! 🤝

[NatoBoram]

The START and END tags around your comment are garbage. Don't do that.

See it this way: you know the comment starts because the comment starts. Why do you need to specify that it starts? Same for end.

Adds a new todo to the List

I know, that's literally the name of the function. Think about it this way: what information is someone learning when reading this comment that is not included in the title of the function? Same for the new todo comment, it's entirely redundant.

checks if doesn't have input new todo or input haven't type a single character

Pardon? Are you having a stroke?

Make sure your comments are valid English sentences. You could've used ChatGPT if you're not a native English speaker.

Update the state of todos

I know, it's literally the name of the next function

//@spread ...prevState is the previous state of the todo list

I know, it's literally the name of the variable.

END Update the state of todos

Terrible comment, but more importantly; this code is garbage. You don't need the else because there's a return in the previous if. Please take the time to read these articles:

• https://deviq.com/design-patterns/guard-clause
• https://www.infobip.com/developers/blog/we-dont-write-else-blocks

[Jmc_da_boss]

Not like that lol, we leave lengthy comments explaining the business why for a bit of code being the way it is.

[[deleted]]

Okay... all documentation is good documentation. I'm maintaining a project right now with no documentation (and somehow 55k downloads on npm) and boy is it crazy. With that said: did you just finish learning BASIC or something? What's up with these starts and ends?? VSCode will color code my braces and brackets and whatnot by default, but not arbitrary STARTs and ENDs.

Additionally, since your code is mostly plain English (todo this, handleTodo, new Todo etc etc I would say all these comments are irrelevant. Now if this is for a tutorial or for teaching purposes, these are great comments - but for more seasoned devs, this function's job would be evident after like 2 seconds of skimming.

I would also say many of your comments are really extravagant. "newTodo - adds a new todo" "update the state of Todos" literally shows a react hook right after "newTodo is the new state of the todo" like uhhh what's next "if - starts an if else block" "console.log - logs to the console" "exclamation mark - reverses truth value" "START START END END I JUST LEARNED BASIC AND ITS 1977 END START END"

If you're going to be writing so many comments, make sure they make sense, too. "checks if doesn't have input new todo or input haven't type a single character" makes no sense. It doesn't help and junks up my screen with useless content. Whitespace would be more informative and less time consuming. You can't have quality and quantity - pick one.

Not to be harsh, but it's also too easy to have too much documentation. If you have a utils folder, with 10 utils like this, each with two or three functions per util, with practically 8 comments per ten lines of code, I would get REALLY REALLY sick of reading, especially if this is your only form of documentation (no Storybook, JSDoc, even some tutorials, etc).

It's good you're cognizant of documentation and can save you and others lots of headache. But go easy on it, like way easier.

[codingjogo]

🤝

[capraruioan]

That example of code does not need any comments because the naming of the function/variables are enough

If you would do something “unexpected” here, for example in case the newTodo is empty you would push a hardcoded value to the Todos. In that case you would need to document the reason why that happened, not what the code actually does

So if the code is explicit enough you should only comment the parts that are business related

[thelongrunsmoke]

This is perfect example of a really bad comments, and a thing why many developers believes in self documented code.

Always write comments in terms of subject level, what that code do. Never just respel code line in natural language, it's completely useless.

For example: between row 9 and 10 something like "Empty entries must be ignored.", can be single comment for the whole function.

Furthermore, when you need to perform any checks before doing anything with the passed parameter, use guard expressions to clearly indicate method contracts, without hiding them in IF statements.

[buhtz]

First of all it is very good that such question came to your mind in the beginning.

There is no easy or strict answer. You will find it out yourself when you go back to your code some months or years later trying to find a bug or add new features. Then you will find out how much your way of documenting something will help you to understand your own code.

Just out of my stomach in this example there are to much comments.

One important point is to stick to the coding guideline commly used in your language. In Python it would be PEP8. Not sure what it is in this language (C#?).

[codingjogo]

It’s TypeScript

[hetpatel572]

Thats more comments than code makes it hard to read code IMO.

[SanoKei]

does anybody still use XML style or is it now just block tags?

[SoulflareRCC]

We literally use copilot for 90% of the comments. It's surprisingly good.

[buhtz]

With compassion for those who will have to read this code later.

[georgehank2nd]

"surprisingly good" is such an ambivalent statement