Why you should NOT write comments in your code

You should not write comments in your code. This video explains why I believe this to be true. Please feel free to comment whether you agree or disagree.

► Buy me a coffee ◄

[stephaneperisset]

Nice troll. :)
I think we'll all agree that clean code should be as readable as comments, thus making those redundant or worse.
But the reality is that the business your software deals with may not be "readable" by a developer: you always end up having very efficent, concise code that involves complex data access requests or math formulae that will never be as readable as a nice comment.
I'll keep on writing comments for the sake of readability of these, and I very much think it is adviseable to do so.

[henkpoell]

IMHO, without comments good code will provide:
- almost 100% of the functionality.
- 80% of what is going on.
- 50% of why things are happening.
So... My guess is that comments fill the gaps there! I sometimes write comments first of what/why stuff happens, and then do the coding in between the comments. Helps a lot if you have to finish the other half the next Monday. Surely, with halfway decent naming you can skip comments like the one on the line below:
sendCancellationMessage(targetUser, language, productList); // Send message to the target user about this cancellation...

[sumaira-sanaullah]

Comment the reason for writing code makes sense and easy to read and understand why the code was written at first place. Finding comments in source control is not always useful in my experience.

[dennisdotnet]

One problem with putting comments in source control is that code often out lives source control. I recently worked with a 300KOC project that was 20+ years old and had been in 5 different source control systems. There was no group that clearly owned the code, a separate group entirely owned source control. They said moving to new system in X time. The management had programmers working on hot items, so on the last day, one programmer took it on his self to check everything out of the old system and into the new system. No history, no comment, just the last checked in version.

[theMosen]

Don't listen to this guy. Please continue to comment wherever you feel the intent might not be immediately obvious. Even if it just saves someone ten seconds in understanding what is going on, it will be appreciated. I can't stand this kind of impractical purism.


Sincerely, someone who might have to go through your code.

[KayOScode]

Sometimes for my classes I try to make my code as unreadable as possible so that when it works the grader is surprised. I write double for loops on one line and name variables with one letter. Then I do like 5 layers of array indexing and setup with no explanation whatsoever. Its fun actually

[mrewan]

"... refactor in Visual Studio": nice if your language can do that. What if you're working in an environment where you don't have the luxury of writing optimal code, but just have to get something working. Comments can say what you would like, why you're not doing it right now, and what how you might improve the code, if ever there is time. You can also say "we would use ___ in <language>, but as <this_language> doesn't have <inbuilt_function>, we do ___ as a kludgy work-around. When <this_language> is next updated, we might be able to alter the code".

Or documenting a non-typical, unexpected, but allowable use of some functionality, that might look "wrong"; so that a later editor doesn't just say "what's this rubbish - delete - why doesn't it work now?"

[dennisdotnet]

I agree with the comments you are talking about not belonging in code. But there are other reason for comments.
My favorite comments are negative knowledge comments; why I did not do something different.
Are summary blocks not comments?
TODO:s?
If multiple people are making multiple changes related multiple features/change orders I like to add a comment to every point of change with my initials, date, and change order number. When I merge back into the main branch, I can see which changes my group made, and if something breaks, I can find what recently changed. After some period of time (6 months to a year) with no trouble, I often go back and removed those comments

[msizinkosi]

So apart from all the positives that come with commenting your code, you are saying we should abandon the practice just because MAYBE someone will one day change the code logic and MAYBE forgets to update the comment as well rendering it useless, is that the only motivation ??

[felixbertoni]

As a C/Assembly/C++ programmer, cannot agree with you about this, yet i agree at some point.
Yes, code is supposed to be sufficiently clear to be understandable alone. And yes, comments may become incoherent if they are not changed at the same time their relative code is changed.
So, why would you write comments ?.

The code itself describes WHAT the code does, while comment describes whant the code SHOULD do, and WHY it should do it. The difference is really important, since it is an help for understanding and debbuging your code. They will be useful anywhere you do something that is "not conventionnal". For example, to recall a property of an object that can't easily be seen, as a "never null pointer" ensured by verifications elsewhere in the code : "no need to check for null, here already verified into [methodName]". If the said property is broken by changes in code, and you get an error here, you will go right to the new code and see "oh, it is not checked anymore"', thus ask the one that has done it (or even better, he may have added a comment to say why not checked ;)), and update the bugged code section and comments. Comments, to summarise, provide a "second point of view" into the story written by your code, and the incoherence between code and comments works as a warning.

To answer the second argument, the comments have to be updated at the same time you update your code. This is a matter of wether you code well or not (this is only my opinion about good coding xD). The same matter that will decide weither you do units tests etc. When you refactor code, you will also check (and refactor if needed) the code that is dependent. Programming is something that require to apply strict rules, and updating comment is no more than appliyng a coding method, you just have to push yourself to do it, as you would push yourself to keep code clear or write tests.

I'll add before concluding, that use of comments will depend a lot about the context, the language and the program created. Working with JavaScript, in a personnal, solo, and at basic skill (just adding some interactivity to HTML code) i would write nearly no comments, because the code is really clear itself since i only manipulate the HTML/CSS, non critical, and if i need maintenance after a long time i will probably rewrite the entire function more than updating it. If you work on, lets say, a game engine, you risk to have a team that don't forcibly know the whole domain (physics, graphics, networking, gameplay, ...), and probably want a really robust code, needing performance. You will surely break some "physics domain" conventions to optimize your code, or adapt gameplay code to adapt it to real-time networking problems, and there, a lot of comment will be needed to help the physician that works with you know that you don't follow the conventions he knows on purpose, why you do it, and how you do it. You will also be relieved to see a comment somewhere YOUR code changed because a tester saw an error occuring and he was skilled enough to correct the code by himself.

In conclusion, we can say wether you comment or not depends of several parameters, but that in general-purpose code, having some comments explaining it can greatly improve it's quality and reusability. Comments are a communication channel, that will never be lost (as long as you have the source code) as a conception document can be. Too many comments can darken the code, but remember that any well-setup programming text editor will be able to hide comments easily.
Bonus : comments can also enlight your code, if you write jokes for example, and can help making your code pleasant to read and review, but don't abuse of this or you can confuse reader even more...

I am for sure open to discussion, and currently preparing a video about "coding style", which will, for sure, include some comments guidelines and pro&cons. I don't know when i will publish it, since i don't have a lot of time for editing currently x)

[kevinl]

I don't think its correct to say that, I have two good reasons why writing comments are useful.
1. to explain the business logics behind the codes so that someone doesn't familiar with the requirements could understand better.
2. some times when code get complex I write some comments so that others can understand it faster, its quicker to read the comments then follow the code. It save time even for myself when need to fix bugs or revisit it few month later. I am not talking about university projects here.

perhaps you should change your title to "Should not write comments for everything".

[balazs.hideghety]

I know it sounds weird: use NO comments...
I do rarely write useful comments (1 per class maybe), and I do have comment lines, those nice green comment lines I really use just to separate some code-parts - even in cases when the function consists just of 10 lines (maybe I do that in the hope that if anyone else touches the code aft. me, he'll do some kinda of grouping and not just doing mess...) :D

[foobar]

What did you use to create the blog on the codeshare website, did you use uBlogsy package or something else? Kind regards.

[goldrushadventureracing]

I like comments! Comments can be useful when describing the why (business reason) for a certain process or display. Source control in my experience doesn't display comments with the relevant emphasis on permanence of the comment. You don't want this kind of comment buried in a list of low level fix descriptions. Also, there are so many techniques that i often come across ways of doing things that may not be initially clear tome and it can take a while to reverse engineer to figure out what it actually does, though you would probably claim this was coded with poor naming if this is the case.

[reachingnexus]

//leave a comment
I like to layout my classes and methods in sudo-code comments first and then delete the comments that are redundant if the code is human readable. This helps ensure that my code stays on track and doesn't bloat with unrelated work. It focuses on the job that needs to be done, keeps it clean and concise. I only leave the comments on items that are not easily human readable.
//summary
sudo-code your comments first then delete the redundant ones

[GamerPolygon]

Try writing SQL query with no comments in it. You wouldn't last long in employment.

[ZamesC]

While I was an early advocate of "self-documenting" code styles (going back to the 1980s), I'd never abandon comments entirely. For a simple reason, the code can only tell you what it does. The comment is there to tell you what it's SUPPOSED to do. This comes particularly important when trying to optimize or refactor the code --- it's impossible to tell what's a necessary action and what's just a side effect without a comment to guide you.

- As for the problem of comments getting out of date -- this is addressed by Does/supposed to do --- If there is a discrepancy between the code & the comment, than the code is, by definition, wrong.

- As for using the check comment instead -- that just sound crazy. You're admiing a need for comments --- so you want to put them in a place where they are difficult to read. Why not put them where you need them -- right in the code (Note-- Check-in comments do serve an important purpose, just not as a replacement for code comments)

[JamieGaProgManTaylor]

I wonder whether you could have shown an example. I know that you run through an example, verbally, but mocking something up and changing it could be useful.

"This method is pretty well written with lots of comments. But what happens when I change the method or the API contract? See how the comments go out of sync quickly? Let's take a look a way to mitigate this by removing the comments and changing the code itself... "

That sort of thing.

Other than that, I like what you have to say here. Especially with "comments can quickly go out of date" comment (not pun intended). Proper variable and function names will always be better than huge swaths comments. Unless you're willing to go through every piece of code that a change touches and update them all

... neither am I.

I'd recommend that viewers take a look at Code Complete 2 (the second edition of Code Complete) by Steve McConnell, as it's full of useful advice like this and has a MASSIVE chapter on comments and where they can be appropriate and useful.

Remember we write code for other humans to read, primarily. If the code is terse and requires the comments, think about refactoring it and making the code clearer. The compiler will still apply the same optimisations behind the scenes.

[vandanarai]

Sorry Paul but I do not agree with you that one should not write comments in the method/function. Because consider a scenario where your client keep changing the requirements every 4-5 months. Suppose your client is an government organization and its a long term project.

If you do not write comments what that particular piece of code does another guy would have not clue what changes had been done earlier.

[ibrahimnada]

i think you are making a good point there