The first thing I do is write a comment block. Where I work, it is very unusual to be given a specification on what has to be done. (Most management types are mechanical engineers.) I then use the comment block as my coding specification and I code to it. Then, sometimes, I update the coding block to match the code.

Me we need to end this myth that code is EVER as clear as well-written English.

Jeff Really? Most of the english I read online is anything but well-written. At least code compiles (or interprets, if that’s your cup of tea).

I submit that badly written (but semantically correct) English is STILL much clearer than non-trivial readable code that compiles. As someone mentioned, comments give you context and the why. Code alone NEVER gives you that.

And I’d have a hard time coming up with an example of proving the exact opposite point of the one being discussed than your square root approximation example.

One of the most important lessons I learned from my mentor is that code should be intuitive. Code could/should in many cases be self explanatory and easy to understand. Commenting isn’t a bad practice, but abuse of commenting code is. I see commenting as something I do as a last option. I think of commenting code as adding spice to food; just a little is fine, but too much ruins the flavor.

I have a really horrible memory, so as I go through a piece of someone else’s code I like to write down what each piece of code does, otherwise I would forget. I find the best place to write down what a piece of code does is as a comment sitting right next to that piece of code. Generally as I work through code, I insert one comment for about every four lines. or five or six if there is nesting. These comments each tell what that little block of code does. When someone will not allow me to add comments to their code that is like saying I’m not allowed to understand it. Conversely, I have been complemented by people who say that my commenting is useful and valuable.

Not everyone thinks the same way. Someone who says code should not be commented is an elitist way of saying that there are certain programmers who should not be allowed to program because they don’t think the right way. Programming is a tool. It is the way we embed our thoughts in technology. If we prevent commenting, we lose the value that people who need to comment can provide.

It’s a shit-ton easier to dive into random code when it’s got neat line-by-line comments (within reason, but anything potentially confusing should be commented). Lot’s of comments aren’t an excuse for bad coding practices, but there’s no reason not to include them. Space is cheap and you can always globally turn them off from being displayed if it irritates you that much.

I like what Robert Martin wrote in his book “Clean Code,” which I think is an excellent book, and I don’t often think or say that. Assuming I understand/remember his points correctly, he was very much into creating very short methods, with as few parameters in the method signature as possible, with highly readable method names. This made the code extremely readable. While it might take some time to refactor a 100 line method into 20 separate methods with clean names and 5 lines of code each on average, it does make for very readable and maintainable code.

I agree that comments can be helpful, especially for strange cases, but I also agree that they are not necessary if code is broken down into short, easy to understand, well-named methods. It makes the code much easier to understand and maintain and breaks down the intent to 5 to 10 easy to digest lines instead of 100 lines. It helps to make the comments less necessary.

I also feel that maintaining a lot of comments is a lot of extra time and effort, that many people do not have time to do or bother to do, especially when they update or change something later or if it is someone else’s code. People start to ignore the comments because they can be inaccurate / out of date as time goes on.

Also each method should do exactly one thing, I believe, is a rule that was mentioned. I am not sure this is always easy or possible, but it makes each method’s purpose clear and easy to comprehend if it can be accomplished.

I just questioned the readability of some code, and I was told that it didn’t need comments because it was “understood at the time”. Instead of accepting that lack of comments lead to my confusion, I was pointed to your blog post. I’ve never ever been burnt by bad comments, I only get burnt by lack of comments, and telling junior devs “you don’t have to comment it if you understand it” truly misunderstands the junior developer mindset. I’m seeing devs not putting comments because the message they are getting is “if it has comments, you’re doing it wrong.”

Comments are much easier to read because all IDE’s present them in a different colour. So it’s easy to just scroll through the code and read the comments to get a gist of what’s going on. Plus, it can help to keep track of the program flow, like if you comment

//start of file validation
//validate number of rows
//validate addresses

etc.

Of course, this can be achieved by method names, too. But as I’ve said, method names don’t stand out as much, plus they are not readable at a glance, most of the time.

Compare: "ValidateAddresses()" to “validate addresses”. The latter is much easier to read at a glance.

If I want to know what a piece of code does, I of course could read through all of the code, plus code put in different classes, plus projects referenced in the code, and so on. Or I could just read a comment block written in humanly processable language. There’s only so much you can “describe” with clever variable, method and class names. But who wants to use a method named “CopyFilesFromAGivenSourceToAGivenDestinationAndDeleteCopiedFilesAtSourceButNotFilesThatWhereNotCopied(string sourcePath, string destinationPath)”?

Why not just name the method “CopyFiles(string source, string dest)” and write a small description in the summary like this

///<summary>
/// Copies files from source path to destination path.
/// This will delete any file that got copied but won't delete files that where not copied
///</summary>

Shows up in the IDE too and anyone who wants to use it knows exactly what it does without having to look at the code, which saves time and is just so much easier.

I guess the “anti comment” fraction is taking things too far. They are too afraid of “bad” comments that they say we should abandon all comments alltogether. But at the same time, they too welcome “good” comments that explain WHY a code does what it does… but isn’t this against their own dogma? Why should I explain WHY a code came into existance in a comment when I’m told to not comment at all?

A (somewhat bad) example:

//During a meeting with $client they told us people have to be of a certain age to use their product
//It was decided on 01-01-1970 that users should be at least 32 years old
const int MINIMUM_AGE = 32;

explains why we set MINIMUM_AGE to 32. However, I was told I shouldn’t use comments. So…

const int MINIMUM_AGE = 32;

What? Why 32? Why such an arbitrary number? Surely it wouldn’t hurt to set this to a nice, round 30, right? Ok, so we have to explain this to the next guy with code: