June 8, 2018 at 12:02 pm
Brain2000 - Friday, June 8, 2018 11:59 AMroger.plowman - Friday, June 8, 2018 11:43 AMBrain2000 - Friday, June 8, 2018 11:07 AMI find comments are easier to return to months or years later if you leave out almost all articles, such as "it" or "this". There's nothing like looking back and trying to figure out what "apply this thing to that so it works out right" even means.Most code should also be self documenting so it will require minimal comments.
Except there is no such thing as self-documenting code. The problem is code needs to be concise to the point it loses context. You keep that context in your mind while you're writing it but context rarely makes it to long term memory. Thus 6 months later you have the code but no context.
Comments record the context so you don't lose it.
Right, concise and to the point. And the variables need to be named correctly. And the functions named properly. And classes where methods are grouped appropriately with proper inheritance.
You know, all the things that work together to create self documenting code!
June 8, 2018 at 12:20 pm
Brain2000 - Friday, June 8, 2018 12:02 PMBrain2000 - Friday, June 8, 2018 11:59 AMroger.plowman - Friday, June 8, 2018 11:43 AMBrain2000 - Friday, June 8, 2018 11:07 AMI find comments are easier to return to months or years later if you leave out almost all articles, such as "it" or "this". There's nothing like looking back and trying to figure out what "apply this thing to that so it works out right" even means.Most code should also be self documenting so it will require minimal comments.
Except there is no such thing as self-documenting code. The problem is code needs to be concise to the point it loses context. You keep that context in your mind while you're writing it but context rarely makes it to long term memory. Thus 6 months later you have the code but no context.
Comments record the context so you don't lose it.
Right, concise and to the point. And the variables need to be named correctly. And the functions named properly. And classes where methods are grouped appropriately with proper inheritance.
You know, all the things that work together to create self documenting code!
Except, none of that provides context (the "why" of the code). All it provides is the "how" of the code, and the "what". But not why the code was written the way it was, what decisions are behind the algorithms chosen, why that particular approach was taken, and so on.
That information is crucial when it comes time to modify the code. Knowing the reasons behind the code let you decide how to modify it to handle new circumstances. It ALSO reminds you about side effects the code may have concerning some distant part of the system, especially in cases where there's some unusual situation that only occurs rarely but absolutely must be handled.
Not to mention the fact English conveys this information much more rapidly than code ever can. Code must be analyzed, comments merely have to be read.
It's like the difference between tactics and strategy. "Self-documenting code" allows you to make tactical decisions. Comments allow you to make strategic ones. After all, nobody likes winning a battle only to lose the war.
June 9, 2018 at 7:08 am
HighPlainsDBA - Friday, June 8, 2018 11:34 AMAn aside... years ago I watched a video where John Carmack was talking about why he had released some source code to the public domain and one of things he mentioned struck a chord with me and he basically said the code itself wasn't worth nearly as much as the countless decisions that when into making it.
That's absolutely brilliant. It's why keeping light weight decision records in Git MD files is a worthwhile practice.
June 9, 2018 at 7:20 am
roger.plowman - Friday, June 8, 2018 12:20 PMBrain2000 - Friday, June 8, 2018 12:02 PMBrain2000 - Friday, June 8, 2018 11:59 AMroger.plowman - Friday, June 8, 2018 11:43 AMBrain2000 - Friday, June 8, 2018 11:07 AMI find comments are easier to return to months or years later if you leave out almost all articles, such as "it" or "this". There's nothing like looking back and trying to figure out what "apply this thing to that so it works out right" even means.Most code should also be self documenting so it will require minimal comments.
Except there is no such thing as self-documenting code. The problem is code needs to be concise to the point it loses context. You keep that context in your mind while you're writing it but context rarely makes it to long term memory. Thus 6 months later you have the code but no context.
Comments record the context so you don't lose it.
Right, concise and to the point. And the variables need to be named correctly. And the functions named properly. And classes where methods are grouped appropriately with proper inheritance.
You know, all the things that work together to create self documenting code!
Except, none of that provides context (the "why" of the code). All it provides is the "how" of the code, and the "what". But not why the code was written the way it was, what decisions are behind the algorithms chosen, why that particular approach was taken, and so on.
That information is crucial when it comes time to modify the code. Knowing the reasons behind the code let you decide how to modify it to handle new circumstances. It ALSO reminds you about side effects the code may have concerning some distant part of the system, especially in cases where there's some unusual situation that only occurs rarely but absolutely must be handled.
Not to mention the fact English conveys this information much more rapidly than code ever can. Code must be analyzed, comments merely have to be read.
It's like the difference between tactics and strategy. "Self-documenting code" allows you to make tactical decisions. Comments allow you to make strategic ones. After all, nobody likes winning a battle only to lose the war.
Needs to be a mixture of both. Self documenting code is essentially a standard in many style guides and something organizations like Google emphasize as opposed to constantly writing comments for every line of code. This does not mean code comments are removed, but as I pointed out in previous posts, defining a header per class, function, method, etc should be adapted to define what's going on and to your point, the purpose with examples. That way you can use your line comments to annotate key parts of the code for further explanation that matches that header ALONG WITH those styles that help you essentially, self document.
June 11, 2018 at 6:55 am
xsevensinzx - Saturday, June 9, 2018 7:20 AMroger.plowman - Friday, June 8, 2018 12:20 PMBrain2000 - Friday, June 8, 2018 12:02 PMBrain2000 - Friday, June 8, 2018 11:59 AMroger.plowman - Friday, June 8, 2018 11:43 AMBrain2000 - Friday, June 8, 2018 11:07 AMI find comments are easier to return to months or years later if you leave out almost all articles, such as "it" or "this". There's nothing like looking back and trying to figure out what "apply this thing to that so it works out right" even means.Most code should also be self documenting so it will require minimal comments.
Except there is no such thing as self-documenting code. The problem is code needs to be concise to the point it loses context. You keep that context in your mind while you're writing it but context rarely makes it to long term memory. Thus 6 months later you have the code but no context.
Comments record the context so you don't lose it.
Right, concise and to the point. And the variables need to be named correctly. And the functions named properly. And classes where methods are grouped appropriately with proper inheritance.
You know, all the things that work together to create self documenting code!
Except, none of that provides context (the "why" of the code). All it provides is the "how" of the code, and the "what". But not why the code was written the way it was, what decisions are behind the algorithms chosen, why that particular approach was taken, and so on.
That information is crucial when it comes time to modify the code. Knowing the reasons behind the code let you decide how to modify it to handle new circumstances. It ALSO reminds you about side effects the code may have concerning some distant part of the system, especially in cases where there's some unusual situation that only occurs rarely but absolutely must be handled.
Not to mention the fact English conveys this information much more rapidly than code ever can. Code must be analyzed, comments merely have to be read.
It's like the difference between tactics and strategy. "Self-documenting code" allows you to make tactical decisions. Comments allow you to make strategic ones. After all, nobody likes winning a battle only to lose the war.
Needs to be a mixture of both. Self documenting code is essentially a standard in many style guides and something organizations like Google emphasize as opposed to constantly writing comments for every line of code. This does not mean code comments are removed, but as I pointed out in previous posts, defining a header per class, function, method, etc should be adapted to define what's going on and to your point, the purpose with examples. That way you can use your line comments to annotate key parts of the code for further explanation that matches that header ALONG WITH those styles that help you essentially, self document.
Oh, I don't disagree but where we differ is "annotate key parts of the code". My position is ALL parts of the code are "key", and you should, in the comments, create a parallel program in English to go along with (and teach) the reader what the code is doing, why it is doing it, and explain why alternate approaches were rejected.
Obviously, lines like "Counter += 1" don't require in depth analysis 🙂 but need a casual mention in the comments to keep the flow of the English program from jarring the reader out of the flow.
My philosophy is "fold all comments, then skim down the comment section headers until you reach the code of interest, then if the code confuses you (and it will) unfold the comment in that section to find out what's going on."
Of course creating and maintaining such extensive tutorial comments takes a lot of time. But that time is more than repaid when it comes time to change the code months or years later, both in actual code change time and in ensuring you actually understood all the ramifications of changing the code, thus preventing unforeseen problems resulting from the change.
There's a reason our company specifies 70% comments to 30% code... :laugh:
June 11, 2018 at 7:55 am
I've pasted entire email threads into the comment section of source code modules, or exported them to .msg files, adding them to the project to supplement the source code.
"Do not seek to follow in the footsteps of the wise. Instead, seek what they sought." - Matsuo Basho
June 11, 2018 at 10:11 am
roger.plowman - Monday, June 11, 2018 6:55 AMxsevensinzx - Saturday, June 9, 2018 7:20 AMroger.plowman - Friday, June 8, 2018 12:20 PMBrain2000 - Friday, June 8, 2018 12:02 PMBrain2000 - Friday, June 8, 2018 11:59 AMroger.plowman - Friday, June 8, 2018 11:43 AMBrain2000 - Friday, June 8, 2018 11:07 AMI find comments are easier to return to months or years later if you leave out almost all articles, such as "it" or "this". There's nothing like looking back and trying to figure out what "apply this thing to that so it works out right" even means.Most code should also be self documenting so it will require minimal comments.
Except there is no such thing as self-documenting code. The problem is code needs to be concise to the point it loses context. You keep that context in your mind while you're writing it but context rarely makes it to long term memory. Thus 6 months later you have the code but no context.
Comments record the context so you don't lose it.
Right, concise and to the point. And the variables need to be named correctly. And the functions named properly. And classes where methods are grouped appropriately with proper inheritance.
You know, all the things that work together to create self documenting code!
Except, none of that provides context (the "why" of the code). All it provides is the "how" of the code, and the "what". But not why the code was written the way it was, what decisions are behind the algorithms chosen, why that particular approach was taken, and so on.
That information is crucial when it comes time to modify the code. Knowing the reasons behind the code let you decide how to modify it to handle new circumstances. It ALSO reminds you about side effects the code may have concerning some distant part of the system, especially in cases where there's some unusual situation that only occurs rarely but absolutely must be handled.
Not to mention the fact English conveys this information much more rapidly than code ever can. Code must be analyzed, comments merely have to be read.
It's like the difference between tactics and strategy. "Self-documenting code" allows you to make tactical decisions. Comments allow you to make strategic ones. After all, nobody likes winning a battle only to lose the war.
Needs to be a mixture of both. Self documenting code is essentially a standard in many style guides and something organizations like Google emphasize as opposed to constantly writing comments for every line of code. This does not mean code comments are removed, but as I pointed out in previous posts, defining a header per class, function, method, etc should be adapted to define what's going on and to your point, the purpose with examples. That way you can use your line comments to annotate key parts of the code for further explanation that matches that header ALONG WITH those styles that help you essentially, self document.
Oh, I don't disagree but where we differ is "annotate key parts of the code". My position is ALL parts of the code are "key", and you should, in the comments, create a parallel program in English to go along with (and teach) the reader what the code is doing, why it is doing it, and explain why alternate approaches were rejected.
Obviously, lines like "Counter += 1" don't require in depth analysis 🙂 but need a casual mention in the comments to keep the flow of the English program from jarring the reader out of the flow.
My philosophy is "fold all comments, then skim down the comment section headers until you reach the code of interest, then if the code confuses you (and it will) unfold the comment in that section to find out what's going on."
Of course creating and maintaining such extensive tutorial comments takes a lot of time. But that time is more than repaid when it comes time to change the code months or years later, both in actual code change time and in ensuring you actually understood all the ramifications of changing the code, thus preventing unforeseen problems resulting from the change.
There's a reason our company specifies 70% comments to 30% code... :laugh:
Counter += 1 might need a little analysis depending on the code around it.
If you were looping through database records and you were adding up hours, perhaps it could be named "hoursCounter". If you were looping through timesheets that contain different types of hours (regular, overtime, sick, etc...), then it could be even more specific, such as "overtimeHoursCounter".
You might even see a line "if (regularHoursCounter > 40) calculateOvertime( )"
It's practically speaking to me.
June 11, 2018 at 10:36 am
In 25+ years of coding, my reasons for commenting code have changed, and it's currently focused on the Who, When and Why of the code, only dealing with the What and How if it's an amazing piece of engineering that you are amazed works even though you just wrote it seconds ago.
The Who, When and Why has been of crucial importance numerous times, especially when debugging some code, and it's determined that X should have a value of Y, but wait, there's a comment that says that "On <when>, <who> requested this to be changed to Z." Now, instead of assuming that the fix is to make X = Y, you now have some context, and very likely, X = Z prior to <when>, and now you've discovered either an edge case or assumptions have changed. You can't assume you've found the answer -- you need to do more work, and you likely need to find other documentation around <when> to decide <why> <who> decided that the change should be made in the first place.
This has happened more times that I can recount. And without that comment, you wouldn't have the full information to proceed safely.
June 12, 2018 at 3:23 am
David.Poole - Friday, June 8, 2018 1:21 AMI've just finished reading "Clean Code" by Robert C Martin. It takes a dim view of commenting code preferring instead to refactor the code to the point where all functions and methods are simple and have meaningful names.
It'll never catch on you know ...
🙁
I'm a DBA.
I'm not paid to solve problems. I'm paid to prevent them.
June 12, 2018 at 3:52 am
LindaEwen - Friday, June 8, 2018 1:40 AMComments can actually make debugging a problem harder. For example: if the comment says this produces a specific date and the code does not do that, which is right? If you can't read the code then you can't debug the program. Writing comments is like writing paragraphs about a symphony - if you can't play the music, reading about it won't help.
And yet, musicians do annotate their scores.
Briefly, to highlight specific pointers, which to me is what code comments should be about
I'm a DBA.
I'm not paid to solve problems. I'm paid to prevent them.
June 13, 2018 at 6:46 am
I used to comment every line of code, when I wrote scripts for the game Heroes of Migth and Magic 3 (WoG), but mostly, because it had a very "uncommon" language, that you not really could read (commands looked all as e.g. !!VR12:S1;).
Today I tend to add a short description to each table / procedure / unusual column and - inside code - a short "headline", what the next block of statements will do.
PS: worst example of a comment:
-- ToDo: fix query xyz
without any information. what was wrong, when this comment was added (and by whom) ...
God is real, unless declared integer.
August 16, 2018 at 2:36 pm
I tend to like having understandable names for most things as a first move towards make code comprehensible. Then explaining the purpose of reasonably sized chunks of code, and the reason for doing it in a particlar way. Sometimes it was useful to state assumptions about other code that my code calls or sends messages to, so that dependencies are plainly visible. Ideally there should be a requirements document for the code, and it makes sense to store that with the code, not somewhare else where someone who doesn't understand the difficulty of understanding or modifying or mending code when you don't know what it's for may delete the requirements statement.
But I have to admit that I've sometimes failed to do adequately helpful commenting - usually when under too much time pressure; shirking on comments can save 20 minutes now and cost 20 hours a year from now when something goes wrong (when something that this code relies on ceases to be true because some bright spark thought that changng something would do no harm and the reliance is not documented, or when additional capability is required and no-one understand how the current capability is provided). And it's not unknown for something that's worked evey few seconds on hundreds of servers for a year or more to stop working and I can't work out why because I can't see how it ever worked at all. On the other hand it's also happened that something suddenly stopped working and I could say what had gone wrong as soon as I was told of the problem, several years after I had written the code, without looking at more than the header comment and spotting a reliance on another component which was the only thing that could be causing the problem, so maybe sometimes I did comment enough.
Tom
Viewing 12 posts - 31 through 41 (of 41 total)
You must be logged in to reply to this topic. Login to reply