Is it okay not to write comments?

Question

I've been coding for about 3 years by now, and never in that period I found it particularly useful to write comments in code just for myself (with some rare exceptions). I try to name functions and variables very clear, and I remember what each function does just fine. If I forget, I just read the code and potentionally come up with new ideas by doing so. Speaking of refactoring: it can often make some comments redundant anyways. So the qustion is: am I doing it all wrong?

Answer 1

I have been trying to get into the habit of doing the following style of comments at the start of each function.

//FunctionName(): short description of the function
//pre-condition: what this function needs set-up to work
//post-condition: the outcome or what changes after the function

Although not mandatory I have found that after coming back to projects after months or years the sporadic commenting on various (seemingly random in retrospect) lines doesn't do enough to remind me what I was thinking at the time.

Answer 2

Just look at my code and you will find I think your wrong. If you want a coding job for a large company, comments are a must. Multi-million line programs must be commented in order to have a clue what is going on. Employers are not willing to pay their employees to figure out what code does after the fact. It must be completely understandable from day one. I can't tell you how many times code failed to be approved during the code review process for lack of meaningful comments during my 44 years in the field. But, I can state people were fired because they continually ignored documenting their code with comments.

Answer 3

At our company we believe comments should be minimal. The reason is simple: comments are just more stuff that needs to be maintained, and if the code around the comment changes but not the comment itself, it becomes dangerous. If the code is written with good variable and function names, the need for comments is minimal.

Answer 4

It is okay not to write comments.
Comments are optional as they will not be displayed in the code output.
But as a checker to self-monitor what you are coding, it's recommended

Answer 5

In the first half of my career, I worked on projects that predominantly required heavy code comments. As I transitioned to agile teams committed to TDD / BDD, general code comments became a liability, rather than an asset to code quality.

Our code review process focuses on readability and test coverage of our code. If we find a comment attempting to explain something in the code, we attempt to explore whether the code could be improved to clarify what ever isolated condition that was being commented. The goal is to let the readability of our code be the source of truth rather than the comments. We can trust the code and the unit tests. However, we cannot trust the comments for several reasons.

1. Comments may not be consistently thorough for all developers and all code.
2. When code changes, comments are not guaranteed to change accordingly and may not be thorough.
3. Comments cannot be validated by the compiler or via unit tests and therefore subject to human error.
4. The context of the comment may have changed as other code has changed. This could cause even more confusion if the comment carries a different meaning in the new context.

Bottom line, comments are not reliable, cannot be tested or validated, and is often redundant to what can be inferred by well written, readable code.

Answer 6

Where I used to work, a project workload is divided, and we had small team with each to their own responsibility and we did different things, or worked on different parts of the project.

IMO if you work in a team writing comments shows your courtesy and responsibility, courtesy here means, if you for some reason cannot attend at work your colleagues can keep the workflow continues, they understand your work, and even if they find difficulties, they can see your comments and figure out which was what and/or when.

One more thing to consider, your work is your legacy, when you leave your place, for better chance or whatever, somebody will take your place, and when that time comes, it is crucial to have well documented work, otherwise it's a waste, of time and resources, further development even if possible, will take much more time, as the new guy cannot absorb your work intention quickly.

Answer 7

First off, thanks for all the replies! Although I think some people misunderstood me. 'For myself' part was crucial. Writing documentation for other people is out of the question. I've worked only on small projects and I did comment them - for others but not for myself. I guess when a project gets much bigger and you have to go back to it years later then yes, it's a must to comment it for yourself and others.