Code comments: How do you comment your code?
-
I'm busy writing a high load TCP server from absolute scratch in C# I've just started to implement the protocol I've been designing over the past few weeks and I really want to make an effort to comment this well because its quite complex and maintenance will be much easier that way, especially if other programmers need to maintain it a few years down the line. I've decided to make use of regions more than inline code comments although the in-lines are still there (usually explaining why your in a specific part of an if statement) So how do you comment your code?
Harvey Saayman - South Africa Software Developer .Net, C#, SQL
you.suck = (you.Occupation == jobTitles.Programmer && you.Passion != Programming)1000100 1101111 1100101 1110011 100000 1110100 1101000 1101001 1110011 100000 1101101 1100101 1100001 1101110 100000 1101001 1101101 100000 1100001 100000 1100111 1100101 1100101 1101011 111111I have seen inline comments to insert a "Note xx Start" and "Note xx End" signaling regions where a big explanation is needed and then in a extern document (or at the end of the file as footer block comments) the whole explanations. i.e.:
//Function boo: Note xx
function boo
{
code
}or inside a big function
function foo
{
1st code snippet
..
// Note xy Start
2nd code snippet
// Note xy End
..
more code
}And the inline just for additions/explanations in particular things
Regards. -------- M.D.V. ;) If something has a solution... Why do we have to worry about?. If it has no solution... For what reason do we have to worry about? Help me to understand what I'm saying, and I'll explain it better to you Rating helpfull answers is nice, but saying thanks can be even nicer.
modified on Friday, January 8, 2010 9:50 AM
-
I'm busy writing a high load TCP server from absolute scratch in C# I've just started to implement the protocol I've been designing over the past few weeks and I really want to make an effort to comment this well because its quite complex and maintenance will be much easier that way, especially if other programmers need to maintain it a few years down the line. I've decided to make use of regions more than inline code comments although the in-lines are still there (usually explaining why your in a specific part of an if statement) So how do you comment your code?
Harvey Saayman - South Africa Software Developer .Net, C#, SQL
you.suck = (you.Occupation == jobTitles.Programmer && you.Passion != Programming)1000100 1101111 1100101 1110011 100000 1110100 1101000 1101001 1110011 100000 1101101 1100101 1100001 1101110 100000 1101001 1101101 100000 1100001 100000 1100111 1100101 1100101 1101011 111111/// Here is my Comment about function Here is my Code /// here is any extraneous explanation------------------------------------ No Good Deed Goes Unpunished Clare Boothe Luce
-
I'm busy writing a high load TCP server from absolute scratch in C# I've just started to implement the protocol I've been designing over the past few weeks and I really want to make an effort to comment this well because its quite complex and maintenance will be much easier that way, especially if other programmers need to maintain it a few years down the line. I've decided to make use of regions more than inline code comments although the in-lines are still there (usually explaining why your in a specific part of an if statement) So how do you comment your code?
Harvey Saayman - South Africa Software Developer .Net, C#, SQL
you.suck = (you.Occupation == jobTitles.Programmer && you.Passion != Programming)1000100 1101111 1100101 1110011 100000 1110100 1101000 1101001 1110011 100000 1101101 1100101 1100001 1101110 100000 1101001 1101101 100000 1100001 100000 1100111 1100101 1100101 1101011 111111Harvey Saayman wrote:
how do you comment your code?
Accurately. :laugh:
All those who believe in psycho kinesis, raise my hand.
-
My thumb says try for 10% inside your methods and use full XML commenting for all external methods. I am trying to get the monkeys developers here to get in the habbit of writting comments BEFORE code. This might aseem stupid but it is very effective. 0. Write comments of what you intend to happen. 1. Write the code. 2. Check it.
Panic, Chaos, Destruction. My work here is done.
Nagy Vilmos wrote:
I am trying to get the monkeys developers here to get in the habbit of writting comments BEFORE code. This might aseem stupid but it is very effective.
Seems anything but stupid, to me. Some of us remember the days when writing code from pseudocode was the norm. It's amazing the number of improvements you can come up with (and logical errors you can spot) by writing down what things will do before writing the code for them.
I wanna be a eunuchs developer! Pass me a bread knife!
-
/// Here is my Comment about function Here is my Code /// here is any extraneous explanation------------------------------------ No Good Deed Goes Unpunished Clare Boothe Luce
Sometimes I don't comment. I do not wish others to change jack about things and hate it when this happens. I have 'My Version' (with comments) and the version I distribute (sans comments). Is this Paranoia?
------------------------------------ No Good Deed Goes Unpunished Clare Boothe Luce
-
Harvey Saayman wrote:
how do you comment your code?
Accurately. :laugh:
All those who believe in psycho kinesis, raise my hand.
OriginalGriff wrote:
Harvey Saayman wrote: how do you comment your code? Accurately.
You keep the crayon within the lines?
I wanna be a eunuchs developer! Pass me a bread knife!
-
Harvey Saayman wrote:
how do you comment your code?
Accurately. :laugh:
All those who believe in psycho kinesis, raise my hand.
We all know the story about the CS teacher who asked his pupils to comment their code. It was full of things like "This is slick Code" and "This works well".
------------------------------------ No Good Deed Goes Unpunished Clare Boothe Luce
-
Sometimes I don't comment. I do not wish others to change jack about things and hate it when this happens. I have 'My Version' (with comments) and the version I distribute (sans comments). Is this Paranoia?
------------------------------------ No Good Deed Goes Unpunished Clare Boothe Luce
I have done it as well. But not only deleting comments, sometimes editing function names (search and replace) with some cryptic / not easy names as well (of course having a relation of the equivalences just in case to be able to reverse it)
Regards. -------- M.D.V. ;) If something has a solution... Why do we have to worry about?. If it has no solution... For what reason do we have to worry about? Help me to understand what I'm saying, and I'll explain it better to you Rating helpfull answers is nice, but saying thanks can be even nicer.
-
Nagy Vilmos wrote:
I am trying to get the monkeys developers here to get in the habbit of writting comments BEFORE code. This might aseem stupid but it is very effective.
Seems anything but stupid, to me. Some of us remember the days when writing code from pseudocode was the norm. It's amazing the number of improvements you can come up with (and logical errors you can spot) by writing down what things will do before writing the code for them.
I wanna be a eunuchs developer! Pass me a bread knife!
When trying to work out what needs to be done, before I actually write any proper code I do a brief Comment and Pseudo code excercise. I find that puts things into a logical order and speeds up work when I get to the nitty-gritty.
------------------------------------ No Good Deed Goes Unpunished Clare Boothe Luce
-
I have done it as well. But not only deleting comments, sometimes editing function names (search and replace) with some cryptic / not easy names as well (of course having a relation of the equivalences just in case to be able to reverse it)
Regards. -------- M.D.V. ;) If something has a solution... Why do we have to worry about?. If it has no solution... For what reason do we have to worry about? Help me to understand what I'm saying, and I'll explain it better to you Rating helpfull answers is nice, but saying thanks can be even nicer.
< Dalek Voice> Obfusticate! Obfusticate! < /Dalek Voice>
------------------------------------ No Good Deed Goes Unpunished Clare Boothe Luce
-
OriginalGriff wrote:
Harvey Saayman wrote: how do you comment your code? Accurately.
You keep the crayon within the lines?
I wanna be a eunuchs developer! Pass me a bread knife!
Mark Wallace wrote:
You keep the crayon within the lines?
Spraycan and a stencil - much easier!
All those who believe in psycho kinesis, raise my hand.
-
OriginalGriff wrote:
Harvey Saayman wrote: how do you comment your code? Accurately.
You keep the crayon within the lines?
I wanna be a eunuchs developer! Pass me a bread knife!
[camp] Ooh! Get you! [/camp]
Panic, Chaos, Destruction. My work here is done.
-
Nagy Vilmos wrote:
I am trying to get the monkeys developers here to get in the habbit of writting comments BEFORE code. This might aseem stupid but it is very effective.
Seems anything but stupid, to me. Some of us remember the days when writing code from pseudocode was the norm. It's amazing the number of improvements you can come up with (and logical errors you can spot) by writing down what things will do before writing the code for them.
I wanna be a eunuchs developer! Pass me a bread knife!
I find anybody who was coding [professionally] more than 15-20 years ago is pretty good on pre-commenting. It's the low order primates that cause me grief.
Panic, Chaos, Destruction. My work here is done.
-
I'm busy writing a high load TCP server from absolute scratch in C# I've just started to implement the protocol I've been designing over the past few weeks and I really want to make an effort to comment this well because its quite complex and maintenance will be much easier that way, especially if other programmers need to maintain it a few years down the line. I've decided to make use of regions more than inline code comments although the in-lines are still there (usually explaining why your in a specific part of an if statement) So how do you comment your code?
Harvey Saayman - South Africa Software Developer .Net, C#, SQL
you.suck = (you.Occupation == jobTitles.Programmer && you.Passion != Programming)1000100 1101111 1100101 1110011 100000 1110100 1101000 1101001 1110011 100000 1101101 1100101 1100001 1101110 100000 1101001 1101101 100000 1100001 100000 1100111 1100101 1100101 1101011 111111Regions aren't an adequate replacement for comments. I comment the code profusely, and in the event that there is a sufficiently complex implementation, I write a separate "How It Works" document in Word, and make check that document into source control with the rest of the project.
.45 ACP - because shooting twice is just silly
-----
"Why don't you tie a kerosene-soaked rag around your ankles so the ants won't climb up and eat your candy ass..." - Dale Earnhardt, 1997
-----
"The staggering layers of obscenity in your statement make it a work of art on so many levels." - J. Jystad, 2001 -
Regions aren't an adequate replacement for comments. I comment the code profusely, and in the event that there is a sufficiently complex implementation, I write a separate "How It Works" document in Word, and make check that document into source control with the rest of the project.
.45 ACP - because shooting twice is just silly
-----
"Why don't you tie a kerosene-soaked rag around your ankles so the ants won't climb up and eat your candy ass..." - Dale Earnhardt, 1997
-----
"The staggering layers of obscenity in your statement make it a work of art on so many levels." - J. Jystad, 2001John Simmons / outlaw programmer wrote:
I comment the code profusely, and in the event that there is a sufficiently complex implementation, I write a separate "How It Works" document in Word, and make check that document into source control with the rest of the project.
That seems very concise, but I, unfortunately, have never written anything so complex as to warrent that. However, I shall bear it in mind if ever I do.
------------------------------------ No Good Deed Goes Unpunished Clare Boothe Luce
-
I'm busy writing a high load TCP server from absolute scratch in C# I've just started to implement the protocol I've been designing over the past few weeks and I really want to make an effort to comment this well because its quite complex and maintenance will be much easier that way, especially if other programmers need to maintain it a few years down the line. I've decided to make use of regions more than inline code comments although the in-lines are still there (usually explaining why your in a specific part of an if statement) So how do you comment your code?
Harvey Saayman - South Africa Software Developer .Net, C#, SQL
you.suck = (you.Occupation == jobTitles.Programmer && you.Passion != Programming)1000100 1101111 1100101 1110011 100000 1110100 1101000 1101001 1110011 100000 1101101 1100101 1100001 1101110 100000 1101001 1101101 100000 1100001 100000 1100111 1100101 1100101 1101011 111111I prefer this: 1. Group related methods in a region. 2. XML style commenting for the methods. You can also keep each method in a region of its own. This removes the scrolling required in case of huge file. 3. If the method is huge, break that into regions as well (better to split it into smaller methods). 4. Every important line/block of code should have a comment before stating what it is doing. 5. In case there are nested if/else, keep footer comments to make sure you don't have to wonder where did you missed that closing "}". 6. In case you have written some "work around" (read weird stuff), do not forget to mention the reason for it or else the other guy would mess that curse you forever. 7. In the end, read the entire file and get rid of excessive commenting.
50-50-90 rule: Anytime I have a 50-50 chance of getting something right, there's a 90% probability I'll get it wrong...!!
-
I have done it as well. But not only deleting comments, sometimes editing function names (search and replace) with some cryptic / not easy names as well (of course having a relation of the equivalences just in case to be able to reverse it)
Regards. -------- M.D.V. ;) If something has a solution... Why do we have to worry about?. If it has no solution... For what reason do we have to worry about? Help me to understand what I'm saying, and I'll explain it better to you Rating helpfull answers is nice, but saying thanks can be even nicer.
Nelek wrote:
editing function names (search and replace) with some cryptic / not easy names
Has anyone ever asked you what
Function FormatCDrive()actually does?I wanna be a eunuchs developer! Pass me a bread knife!
-
Nagy Vilmos wrote:
I am trying to get the monkeys developers here to get in the habbit of writting comments BEFORE code. This might aseem stupid but it is very effective.
Seems anything but stupid, to me. Some of us remember the days when writing code from pseudocode was the norm. It's amazing the number of improvements you can come up with (and logical errors you can spot) by writing down what things will do before writing the code for them.
I wanna be a eunuchs developer! Pass me a bread knife!
-
Nelek wrote:
editing function names (search and replace) with some cryptic / not easy names
Has anyone ever asked you what
Function FormatCDrive()actually does?I wanna be a eunuchs developer! Pass me a bread knife!
hmm, let me just try th
------------------------------------ No Good Deed Goes Unpunished Clare Boothe Luce
-
I'm busy writing a high load TCP server from absolute scratch in C# I've just started to implement the protocol I've been designing over the past few weeks and I really want to make an effort to comment this well because its quite complex and maintenance will be much easier that way, especially if other programmers need to maintain it a few years down the line. I've decided to make use of regions more than inline code comments although the in-lines are still there (usually explaining why your in a specific part of an if statement) So how do you comment your code?
Harvey Saayman - South Africa Software Developer .Net, C#, SQL
you.suck = (you.Occupation == jobTitles.Programmer && you.Passion != Programming)1000100 1101111 1100101 1110011 100000 1110100 1101000 1101001 1110011 100000 1101101 1100101 1100001 1101110 100000 1101001 1101101 100000 1100001 100000 1100111 1100101 1100101 1101011 111111I've been using a simple yet effective rule for writing comments for decades:
- Remove all code except for block boundaries (i.e. everything except stuff in conditional expressions and opening and closing curly braces).
- Do the remaining comments and "code shell" represent the psuedocode fairly accurately?
- If yes, you're done. Else, you need more comments.
It's amazing how well this rule works. Without conciously trying, applying this rule caused me to move from writing few long-winded PhD thesis comment blocks to several small one-line phrases that increase readability many fold. /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
