Notes from reading:
Code Complete: A Practical Handbook of Software Construction, Second Edition by Steve McConnell Link: Amazon
I have been reading this try to improve my skills I figured I could jot down some notes which might help it sink in my brain and who know you might find it interesting.
Author starts out with a play that I think probably every programmer who has worked for atleast a year has been part of. The Character in the play were as follows:
Characters:
THRASYMACHUS A green, theoretical purist who believes everything he reads
CALLICLES A battle-hardened veteran from the old school—a “real” programmer
GLAUCON A young, confident, hot-shot computer jock
ISMENE A senior programmer tired of big promises, just looking for a few practices
that work
SOCRATES The wise old programmer
Pretty much the play sounded very familiar arguments for and against comments. The key point that McConnell put a nice key point marker by I and probably almost everyone can agree with. " Good comments don’t repeat the code or explain it. They clarify its intent. Comments should explain, at a higher level of abstraction than the code, what you’re trying to do."
Types of comments
Repeat of the Code - Author and I agree pretty useless.
Explanation of the Code - These are comments that explain how a tricky section of code. McConnell makes a good point here that this type of comment probably indicates a section of code that needs to written in a clearer manner.
Marker in the Code - Basically a TODO author makes a good point that standardizing these in some way may avoid situations of known bugs getting delivered.
Summary of Code - Author says these are useful as they condense what the code does. I agree that these are useful at the very least you can get the gist of a section. This can allow much faster understanding of the code assuming what is summarized is really done there.
Description of the Code’s Intent - I have found that knowing what the original author was thinking can be useful when getting ready to change a seemingly silly section of code.
The key points in the book are great. Another gem "If you spend a lot of time entering and deleting dashes to make plus signs line up, you’re not pro-gramming; you’re wasting time." Many of his examples of comments that are hard to maintain I have used and have found that keeping them looking good takes more time then it should.
End line comments based on McConnel's points about how they are generally not useful I think I will start trying to avoid them a bit more. I agree that many times if I am adding an end line comment it probably doesn't add much value especially if its for one line of code. Also if I am putting one in I do generally try to make it short.
McConnel does suggest they are okay in the following situations:
- Declaring data
- End of a structure like a for loop- I would contend that generally if you need one to keep track of something like this you might need to try to refactor this section of code.
Another awesome key point "When someone says, “This is really tricky code,” I hear them say, “This is really bad code.” If something seems tricky to you, it will be incomprehensible to someone else. " I agree with the author on this one for sure although it is sometimes useful for helping find bugs as I have found that tricky code often contains them.
McConnel points out that heavy routine comment requirements make adding routines harder and thus people will write bigger routines to avoid them. This is true and I also believe that C++ with the additional overhead of the .h files makes people more likely to avoid routines as well.
Hmm I have never heard of the "The Book Paradigm for Program Documentation" but it is an interesting idea I will have to think about reading more.
