Coding Without Comments

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. :slight_smile:

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.

haha.

comments are a great source of entertainment:
here are a few of my favorites

ā€™ * Iā€™m falling asleep at the keyboard, so no telling how much sense this makesā€¦
(huh? waitā€¦ wake up buddy!)

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.

Hello. Jeff. these comments are as a prototype of the codes and to get my idea of the code out.
Mass Profit Formula Review

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:

const int MINIMUM_AGE_THAT_WAS_DECIDED_ON_DURING_A_MEETING_WITH_CLIENT_X = 32;

Yeah, this sure is so much better. Especially when $client decides users should be 33 now.

const int MINIMUM_AGE_THAT_WAS_DECIDED_ON_DURING_A_MEETING_WITH_CLIENT_X_USED_TO_BE_32_BUT_NOW_IS_DIFFERENT_AS_OF_JANUARY_1ST_2018 = 33;
1 Like

Code comments

Code comments

Code comments

Code comments