Wiki Diff UsingComments, revision #1 to tip
=Tip=
== Commenting ==
[[Back to tips page -> Tips]]
[quote ChrisB]
This weeks tip of the week brought to you by me(!)
Comment your code profusely. Its easy to remember what you wrote that obscure looking line or what those oddly named variables were, or where those global variables / functions were defined when you wrote the code earlier that week, but try to remember what they were in 6 months time!
<eucode>
</eucode>
<eucode>
function add_splodges(integer a, sequence X_ogg)
end function
</eucode>
is a lot harder to understand than
<eucode>
------------------------------------------------
function add_splodges(integer a sequence Xogg)
--a function to add a to all items in X_ogg
--X_ogg - a sequence of oggs
--returns - a sequence of oggs with a added
------------------------------------------------
end function
</eucode>
Whats more, you can block comment with the C construct /* .. */
<eucode>
/*This is a block of code
to explain what I'm about to do here
but the block would be so long as to make putting
-- tedious
*/
--(note, the web page display has 'issues' with displaying the above correctly!
</eucode>
You can also use /* .. */ to temporarily block off a section of code tosee the effect, as if the code were not there.\\
\\
Also its a lot easier for other people to understand and modify your code later - check out the standard libs for an excellent set of examples.
Post your own tips to tw@openeuphoria.org - remember they can be as simple as you like, or as complicated as you want to make them. We're all interested in knowing what you have discovered to help your coding experiences.
Chris
[/quote]
[quote jaygade]
In addition, sometimes it's better to comment your code //before// you actually write it, or even write out the pseudo-code in the comments before writing the actual code.
It is especially important to document functions and procedures, though, and especially helpful to document preconditions, post conditions, and invariants if relevant.
[/quote]
[quote alanjohnoxley]
Agree with that! \\
Its epecially useful when you know what a function is intended to return, before its written.. I find I get carried away inside a bit of code \\
and then forget that the bits i'm trying to shoehorn in, don't actually belong there.
Did you know the bard was a developer/systems analyst too? From Macbeth:\\
"We teach bloody instructions which upon being invented, return to plauge the inventor" :)) \\
Cheers
Alan
[/quote]
[quote DerekParnell]
[quote ChrisB]
Comment your code profusely ...
[/quote]
The true art of commenting is to explain //**why**// your code looks like it does. Looking at the code itself can mostly tell you what its doing but very often you have little idea about why its doing it.
I really hate seeing comments like this ...
<eucode>
wcntr += 1 -- add to counter
</eucode>
Duh~!~!~!
Maybe something more along the lines of ...
<eucode>
-- Keep track of how many widgets we have now.
wcntr += 1
</eucode>
\\
The other important aspect is getting the right ratio of comments to lines-of-code. I try to see code blocks at two levels, similar in concept to //paragraphs// and //sentences//. A code sentence is usually a discrete block of code from one to six or seven lines. The code sentence is a block of code that does one logical micro-task. Usually it has only one branching construct at most in it. When you get one or more code sentences together that together perform a task or //function point//, you have a code paragraph. I feel that most (but not all) sentences need to be explained in their comments and a separate comment should explain what the paragraph is trying to achieve.
Ideally, you should be able to get to the point where you can take out the source code from the program and then get someone else to re-write the application using just the remaining comments.
[/quote]
[quote jeremy]
[quote ChrisB]
Comment your code profusely ...
[/quote]
I'll add one more thing to Derek's response and that is well designed code can just about comment itself. For example:
<eucode>
-- Increment our active widget counter
i += 1
</eucode>
\\
sure, because of the comment we know what's going on, however:
<eucode>
activeWidgetCount += 1
</eucode>
\\
that code needs no comment. This starts with good naming techniques but goes a step further in real practice.
Ideally the code should be self commenting but there will always be sections of code that need that extra bit of explanatory text to make things clear.
Remember a few things about commenting (whether by self-commenting code, code comments or project documentation):
# You may not be the only person trying to understand the given code. If you are today maybe tomorrow you will not be.
# You may know what the code does today and even tomorrow but 10 projects and 5 years later, will you?
[/quote]
----
CategoryTip
=Tip=
== Commenting ==
[[Back to tips page -> Tips]]
[quote ChrisB]
This weeks tip of the week brought to you by me(!)
Comment your code profusely. Its easy to remember what you wrote that obscure looking line or what those oddly named variables were, or where those global variables / functions were defined when you wrote the code earlier that week, but try to remember what they were in 6 months time!
<eucode>
</eucode>
<eucode>
function add_splodges(integer a, sequence X_ogg)
end function
</eucode>
is a lot harder to understand than
<eucode>
------------------------------------------------
function add_splodges(integer a sequence Xogg)
--a function to add a to all items in X_ogg
--X_ogg - a sequence of oggs
--returns - a sequence of oggs with a added
------------------------------------------------
end function
</eucode>
Whats more, you can block comment with the C construct /* .. */
<eucode>
/*This is a block of code
to explain what I'm about to do here
but the block would be so long as to make putting
-- tedious
*/
--(note, the web page display has 'issues' with displaying the above correctly!
</eucode>
You can also use /* .. */ to temporarily block off a section of code tosee the effect, as if the code were not there.\\
\\
Also its a lot easier for other people to understand and modify your code later - check out the standard libs for an excellent set of examples.
Post your own tips to tw@openeuphoria.org - remember they can be as simple as you like, or as complicated as you want to make them. We're all interested in knowing what you have discovered to help your coding experiences.
Chris
[/quote]
[quote jaygade]
In addition, sometimes it's better to comment your code //before// you actually write it, or even write out the pseudo-code in the comments before writing the actual code.
It is especially important to document functions and procedures, though, and especially helpful to document preconditions, post conditions, and invariants if relevant.
[/quote]
[quote alanjohnoxley]
Agree with that! \\
Its epecially useful when you know what a function is intended to return, before its written.. I find I get carried away inside a bit of code \\
and then forget that the bits i'm trying to shoehorn in, don't actually belong there.
Did you know the bard was a developer/systems analyst too? From Macbeth:\\
"We teach bloody instructions which upon being invented, return to plauge the inventor" :)) \\
Cheers
Alan
[/quote]
[quote DerekParnell]
[quote ChrisB]
Comment your code profusely ...
[/quote]
The true art of commenting is to explain //**why**// your code looks like it does. Looking at the code itself can mostly tell you what its doing but very often you have little idea about why its doing it.
I really hate seeing comments like this ...
<eucode>
wcntr += 1 -- add to counter
</eucode>
Duh~!~!~!
Maybe something more along the lines of ...
<eucode>
-- Keep track of how many widgets we have now.
wcntr += 1
</eucode>
\\
The other important aspect is getting the right ratio of comments to lines-of-code. I try to see code blocks at two levels, similar in concept to //paragraphs// and //sentences//. A code sentence is usually a discrete block of code from one to six or seven lines. The code sentence is a block of code that does one logical micro-task. Usually it has only one branching construct at most in it. When you get one or more code sentences together that together perform a task or //function point//, you have a code paragraph. I feel that most (but not all) sentences need to be explained in their comments and a separate comment should explain what the paragraph is trying to achieve.
Ideally, you should be able to get to the point where you can take out the source code from the program and then get someone else to re-write the application using just the remaining comments.
[/quote]
== Commenting ==
[[Back to tips page -> Tips]]
[quote ChrisB]
This weeks tip of the week brought to you by me(!)
Comment your code profusely. Its easy to remember what you wrote that obscure looking line or what those oddly named variables were, or where those global variables / functions were defined when you wrote the code earlier that week, but try to remember what they were in 6 months time!
<eucode>
</eucode>
<eucode>
function add_splodges(integer a, sequence X_ogg)
end function
</eucode>
is a lot harder to understand than
<eucode>
------------------------------------------------
function add_splodges(integer a sequence Xogg)
--a function to add a to all items in X_ogg
--X_ogg - a sequence of oggs
--returns - a sequence of oggs with a added
------------------------------------------------
end function
</eucode>
Whats more, you can block comment with the C construct /* .. */
<eucode>
/*This is a block of code
to explain what I'm about to do here
but the block would be so long as to make putting
-- tedious
*/
--(note, the web page display has 'issues' with displaying the above correctly!
</eucode>
You can also use /* .. */ to temporarily block off a section of code tosee the effect, as if the code were not there.\\
\\
Also its a lot easier for other people to understand and modify your code later - check out the standard libs for an excellent set of examples.
Post your own tips to tw@openeuphoria.org - remember they can be as simple as you like, or as complicated as you want to make them. We're all interested in knowing what you have discovered to help your coding experiences.
Chris
[/quote]
[quote jaygade]
In addition, sometimes it's better to comment your code //before// you actually write it, or even write out the pseudo-code in the comments before writing the actual code.
It is especially important to document functions and procedures, though, and especially helpful to document preconditions, post conditions, and invariants if relevant.
[/quote]
[quote alanjohnoxley]
Agree with that! \\
Its epecially useful when you know what a function is intended to return, before its written.. I find I get carried away inside a bit of code \\
and then forget that the bits i'm trying to shoehorn in, don't actually belong there.
Did you know the bard was a developer/systems analyst too? From Macbeth:\\
"We teach bloody instructions which upon being invented, return to plauge the inventor" :)) \\
Cheers
Alan
[/quote]
[quote DerekParnell]
[quote ChrisB]
Comment your code profusely ...
[/quote]
The true art of commenting is to explain //**why**// your code looks like it does. Looking at the code itself can mostly tell you what its doing but very often you have little idea about why its doing it.
I really hate seeing comments like this ...
<eucode>
wcntr += 1 -- add to counter
</eucode>
Duh~!~!~!
Maybe something more along the lines of ...
<eucode>
-- Keep track of how many widgets we have now.
wcntr += 1
</eucode>
\\
The other important aspect is getting the right ratio of comments to lines-of-code. I try to see code blocks at two levels, similar in concept to //paragraphs// and //sentences//. A code sentence is usually a discrete block of code from one to six or seven lines. The code sentence is a block of code that does one logical micro-task. Usually it has only one branching construct at most in it. When you get one or more code sentences together that together perform a task or //function point//, you have a code paragraph. I feel that most (but not all) sentences need to be explained in their comments and a separate comment should explain what the paragraph is trying to achieve.
Ideally, you should be able to get to the point where you can take out the source code from the program and then get someone else to re-write the application using just the remaining comments.
[/quote]
[quote jeremy]
[quote ChrisB]
Comment your code profusely ...
[/quote]
I'll add one more thing to Derek's response and that is well designed code can just about comment itself. For example:
<eucode>
-- Increment our active widget counter
i += 1
</eucode>
\\
sure, because of the comment we know what's going on, however:
<eucode>
activeWidgetCount += 1
</eucode>
\\
that code needs no comment. This starts with good naming techniques but goes a step further in real practice.
Ideally the code should be self commenting but there will always be sections of code that need that extra bit of explanatory text to make things clear.
Remember a few things about commenting (whether by self-commenting code, code comments or project documentation):
# You may not be the only person trying to understand the given code. If you are today maybe tomorrow you will not be.
# You may know what the code does today and even tomorrow but 10 projects and 5 years later, will you?
[/quote]
----
CategoryTip
