- #1
DaveC426913
Gold Member
- 22,889
- 6,596
When you're commenting your code (and I don't care what language you're writing in), do you comment *before* the subprocedure or *within* the subprocedure? What is the best practice?
eg.
Comment before:
// loop through the following code
for i=1 to 10
---(some code)
---...
---// check truth of x
---if (x) then
------(some code)
---else
------(some code)
---end if
next
Comment within:
for i=1 to 10
---// looping through this code
---(some code)
---...
---if (x) then
------// x is true
------(some code)
---else
------// x is false
------(some code)
---end if
next
I can see advantages and disads of each.
I understand that the post obvious answer is "It doesn't matter, as long as it makes the code understandable." But I like consistency.
eg.
Comment before:
// loop through the following code
for i=1 to 10
---(some code)
---...
---// check truth of x
---if (x) then
------(some code)
---else
------(some code)
---end if
next
Comment within:
for i=1 to 10
---// looping through this code
---(some code)
---...
---if (x) then
------// x is true
------(some code)
---else
------// x is false
------(some code)
---end if
next
I can see advantages and disads of each.
I understand that the post obvious answer is "It doesn't matter, as long as it makes the code understandable." But I like consistency.