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.
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.”