Retrospect's Ramblings

[TheMole]

I still do it the old way. It's the only way when working with assembler (and, I presume, GPL) to remember what the hell you did, and, crucially, why you did it that way some six months later!

 

See here for an example.

 

Well, for assembly, GPL it definitely makes sense as the languages are not very descriptive in and by themselves. I guess you could probably say the same thing for BASIC variants that rely on line numbers, up to a certain extend, However, I cringe when I see code like this in C (or any other reasonably high level language):

 

/**
* Counts the number of times char c shows up in String str
*/
public int countChar(char c, String str)
{
 // intialize the count
 int count = 0;
 // loops until end of string
 for (int i=0; i<str.length; i++)
 {
   // if character in string at position i is equal to c
   if (str.charAt(i) == c)
{
  // increase count
  count++;
   }
 }
 // returns the count
 return count;
}

 

Basically, unless you're doing something that explains part of your algorithm (language independent), or are using some sorts of tricks or optimizations that obfuscate the logic, I feel it's always better to let the code speak for itself as much as possible. The example above would've been just fine with only the comment before the function (or perhaps even without that if a better function name had been chosen).

 

So there's definitely a happy middle ground to be found .

[Willsy]

I fully agree. The higher level languages can be almost self describing if proper variable, function and structure names are chosen. Of course, it's a different issue altogether in the lower level languages.

 

C inparticular often breaks down (for me personally) when pointers (and to a lesser extent, casting) enter the mix. Then you have to pay attention. C's obtuse use of * and & still trips me up after all these years I much prefer Java in that respect, it produces more readable (though often very verbose) code.

[TheMole]

C inparticular often breaks down (for me personally) when pointers (and to a lesser extent, casting) enter the mix. Then you have to pay attention. C's obtuse use of * and & still trips me up after all these years

 

Same here, but only for code that I haven't written myself. The habit of referencing to a variable's pointer's pointer (or similar silly concepts), without using intermediate variables, or helper defines absolutely kills readability. But there's always a better, more readable alternative available in C. Problem with C is that it doesn't force decent coding conventions, and it takes a lot of restraint on the coder's side to maintain a clear code base. Something an awful lot of coders don't have .

[+OLD CS1]

I still do it the old way. It's the only way when working with assembler (and, I presume, GPL) to remember what the hell you did, and, crucially, why you did it that way some six months later!

 

Horse hockey. Real programmers do not comment; if it was difficult to create it should be difficult to understand

 

I know I have looked back on my 6502 code before wondering, what the frak was I thinking when I wrote this? I even have some comments which read, what the frak am I thinking here?

[matthew180]

I think the real problem with all programming is the absolute lack of explaining what the program is doing.

Comments today in source code is so bad as to just frustrate anyone.

The old way of explaining every line has given way to a 2 line comment for a 40 line subprogram. (if you get that much)

 

Explaining *what the program is doing* is the key to commenting. Commenting every line is useless to understanding the overall result. Single line comments help in assembly when you do things like using a shift to multiple or divide, etc. since those types of bit-twiddling are not always obvious.

 

I still do it the old way. It's the only way when working with assembler (and, I presume, GPL) to remember what the hell you did, and, crucially, why you did it that way some six months later!

 

Again, the important factor here is the *why* of it all. I can see some code is looping 32 times, but *why* is it looping 32 times? That's what the comments should explain.

 

Well, for assembly, GPL it definitely makes sense as the languages are not very descriptive in and by themselves. I guess you could probably say the same thing for BASIC variants that rely on line numbers, up to a certain extend, However, I cringe when I see code like this in C (or any other reasonably high level language):

 

/**
* Counts the number of times char c shows up in String str
*/
public int countChar(char c, String str)
{
 // intialize the count
 int count = 0;
 // loops until end of string
 for (int i=0; i<str.length; i++)
 {
   // if character in string at position i is equal to c
   if (str.charAt(i) == c)
{
     // increase count
     count++;
   }
 }
 // returns the count
 return count;
}

 

Basically, unless you're doing something that explains part of your algorithm (language independent), or are using some sorts of tricks or optimizations that obfuscate the logic, I feel it's always better to let the code speak for itself as much as possible. The example above would've been just fine with only the comment before the function (or perhaps even without that if a better function name had been chosen).

 

So there's definitely a happy middle ground to be found .

 

Ahh, if only the functions I were dealing with in my day job were so obvious and cut-n-dry. I don't believe in self-documenting code. Sure, good code lets you quickly understand *what* it is doing, but the code and computer can't tell you *why*, which is what you need to know to validate, fix, or change the code. Why are you looking for a certain character? Why is strlen being used inside the loop? Will the length change over the course of the test? Is this a multi-threaded application? Can the count be negative? If not, why is an int used for the return value? What if the input is longer than an signed int (buffer overflow)? Why is there no bounds checking? Can the input data be completely trusted? Can I modify the functionality without affecting 10-years of legacy code that has been using this function?

 

So even a seemingly simple function can generate a lot of questions that the code simply can't answer, but a few well written comments could.

 

Commenting the *what*, like this, is useless:

 

// Check if x is greater than 32

if ( x > 32 )

 

That comment explains the code and becomes useless. A better comment, that explains the *why* would be:

 

// Check if the player is beyond the right-most screen boundary

// to limit player movement and prevent a run-time error.

if ( x > 32 )

 

From the comment you immediately know what "x" and "32" represent and you also have knowledge about how to change the function. The code simply demonstrates how the computer will perform that test, and can be verified against the comment. Even better if your language supports constants where you could replace 32 with something descriptive like MAX_RIGHT_SCREEN_BOUNDARY.

 

A more typical example that I work with all the time is where the code is dealing with an external data structure, like XML, a database query result, etc. You can see all the code parsing the input, testing data fields against values and such, but unless you know the external format or data model, you can't change the code. However, documenting the external data format with 200 lines of comments next to the 25 lines of code that process that data will place the information necessary to modify (and check) the code right there where it is needed most.

 

Document the *why* (... this algo vs. that algo because ...) and sometimes the *how* (... using approx integer math because floating point is too slow on this platform ...), not the *what*. Most people document the *what* and those comments are useless.

 

[+InsaneMultitasker]

Document the *why* (... this algo vs. that algo because ...) and sometimes the *how* (... using approx integer math because floating point is too slow on this platform ...), not the *what*. Most people document the *what* and those comments are useless.

I agree that documenting the 'why' and 'how' is important but I disagree regarding the 'what' comments. Some of the first assembly code I came across documented the "what". This was critical to my understanding the instructions that were likely obvious to a more seasoned 9900 programmer. The E/A manual was of little help back then and only through other working code did I grasp sufficient knowledge to start creating (and recycling) my own code. Even today I document many lines using a mix of what, how, and why depending on complexity and use. I often go so far as to retain past code, commented and dated, if I think it may be helpful to understand the program's evolution.

 

I know one no-longer active 9900 programmer who felt that because he knew what he coded, comments were useless and a waste of time. In some cases disassembling his programs would produce code just as easy to understand simply because there is no roadmap to tell me, 15 or more years later, what he had in mind back then.

[TheMole]

Explaining *what the program is doing* is the key to commenting. Commenting every line is useless to understanding the overall result. Single line comments help in assembly when you do things like using a shift to multiple or divide, etc. since those types of bit-twiddling are not always obvious.

 

---8<----------8<-------------

 

Again, the important factor here is the *why* of it all. I can see some code is looping 32 times, but *why* is it looping 32 times? That's what the comments should explain.

Commenting the *what*, like this, is useless:

 

// Check if x is greater than 32

if ( x > 32 )

 

That comment explains the code and becomes useless. A better comment, that explains the *why* would be:

 

// Check if the player is beyond the right-most screen boundary

// to limit player movement and prevent a run-time error.

if ( x > 32 )

 

From the comment you immediately know what "x" and "32" represent and you also have knowledge about how to change the function. The code simply demonstrates how the computer will perform that test, and can be verified against the comment. Even better if your language supports constants where you could replace 32 with something descriptive like MAX_RIGHT_SCREEN_BOUNDARY.

 

I don't think we're that far apart, when it comes to commenting philosophy, but if in the example that you're giving the code would read like below (ie, use decent variable naming conventions), the comments you propose are superfluous at best. And since they don't add anything, it's probably better to leave them out to avoid the risk of code and comments getting out of sync after a number of refactoring sessions. I've seen that one too many times.

 

if (player.pos.x > MAX_RIGHT_SCREEN_BOUNDARY)

 

Using numeric constants directly in code should be forbidden, there needs to be a gcc -W flag for that. And variable names have to be descriptive. Except for i (as a loop counter) and x & y (in rare cases where you're doing generic vector math within a simple helper function), single-letter names should be avoided. Complex data types should always be represented by structs (never have player_x and player_y as two different ints), nested where appropriate, etc...

[matthew180]

I agree that documenting the 'why' and 'how' is important but I disagree regarding the 'what' comments.

 

I think we share the same sentiment with regards to the single line comments in assembly. I did say that in my previous post, but maybe not in the best way:

 

Explaining *what the program is doing* is the key to commenting. Commenting every line is useless to understanding the overall result. Single line comments help in assembly when you do things like using a shift to multiple or divide, etc. since those types of bit-twiddling are not always obvious.

 

Single line comments have their place in assembly to point out some non-obvious use or explain something that can't be conveyed in the instruction (like what writing a byte to a specific address might do). But *only* having single line comments in assembly will not help you understand the overall program.

 

I tend to comment every line in my assembly programs, but I also have large comment blocks that explain what the next section of code is going to do, why, how, what algos, etc. Taken together with the single line comments for more detail, it helps me understand what I was doing and why.

Edited August 8, 2013 by matthew180

[Tursi]

Well, for assembly, GPL it definitely makes sense as the languages are not very descriptive in and by themselves. I guess you could probably say the same thing for BASIC variants that rely on line numbers, up to a certain extend, However, I cringe when I see code like this in C (or any other reasonably high level language):

 

/**
* Counts the number of times char c shows up in String str
*/
public int countChar(char c, String str)
{
// intialize the count
int count = 0;
// loops until end of string
for (int i=0; i<str.length; i++)
{
// if character in string at position i is equal to c
if (str.charAt(i) == c)
{
 // increase count
 count++;
}
}
// returns the count
return count;
}

 

Basically, unless you're doing something that explains part of your algorithm (language independent), or are using some sorts of tricks or optimizations that obfuscate the logic, I feel it's always better to let the code speak for itself as much as possible. The example above would've been just fine with only the comment before the function (or perhaps even without that if a better function name had been chosen).

 

So there's definitely a happy middle ground to be found .

 

The problem with your example is not really the quantity of documentation, but rather what it's documenting. The comments don't need to explain what the code is doing - you can see that. The comments are supposed to explain WHY it's doing that.

 

Sometimes this is important even if it appears to be obvious, especially when you are working on a collaborative project with many coders of different skill levels. Someone may come in here and say, "Oh, hell, I can speed this loop up by processing 4 bytes at a time (as a seriously contrived example), only to find it doesn't work in your original application because your memory port is only 8 bits wide. (Yeah, I'm reaching, this is a pretty bad example, but hopefully the point is there.) In that case, the function would need a comment that says "Loop over the characters one at a time because we have only 8-bit access to the device they are stored on."

 

Comments should document intent, assumptions, parameters, and magic. Of course, for functions with none of the above, a simple statement of purpose is, indeed, enough. But such functions are rare.

[Tursi]

Document the *why* (... this algo vs. that algo because ...) and sometimes the *how* (... using approx integer math because floating point is too slow on this platform ...), not the *what*. Most people document the *what* and those comments are useless.

 

Said MUCH better than I did!

[matthew180]

I don't think we're that far apart, when it comes to commenting philosophy, but if in the example that you're giving the code would read like below (ie, use decent variable naming conventions), the comments you propose are superfluous at best. And since they don't add anything, it's probably better to leave them out to avoid the risk of code and comments getting out of sync after a number of refactoring sessions. I've seen that one too many times.

 

Probably not far apart at all. And yes, my examples could have been better if the language supports such constructs (constants, structures, long variable names, etc), but I was partially thinking of languages like ROM BASIC or assembly on a classic computer. Although large blocks of comments don't work so well with BASIC since they consume memory, as do longer variable names.

 

In general though, I prefer to comment first then add the code to do what is described. Then if I need to add comments to specific parts of the code for clarification, the comments have purpose.

[Tursi]

it's probably better to leave them out to avoid the risk of code and comments getting out of sync after a number of refactoring sessions. I've seen that one too many times.

 

I've seen that many times, too, however, that's just sloppiness. Comments are not an afterthought, they are a part of the product. If the person changing the code felt the comments were unnecessary, they should have been removed, not ignored. Then the next person comes along and has to ask "is the code or the comment correct, because I don't know if I just found a bug?"

 

It's fine if you are the only person working on something. But if many people are and will be working on it, you should treat it like you won't be there in five years to answer questions (and you actually want to help that next person).

[RXB]

If you look at TI and the code they used for XB or other carts on ROM and GROM side they comment every single line most of the time.

You have to scan for a lot of lines before you see no comments and never more then 4 or 5 lines before another commomment.

And any routines like that have like 8 lines that describe in detail everything it does.

 

I have made this a habit like my Assembly for IN THE DARK is very commented:

                   TITL       'ENEMY ROUTINES'
                   AORG    >D000
WRKSPC     EQU      $
                  DATA      0		 R0 FOOD:TRAPS
RX               DATA     0		 R1 RXB X
NX               DATA     0		 R2 NEW X
                  DATA     0		 R3 RXB U
                  DATA     0		 R4 SAVED U POSITION 3
                  DATA     0		 R5
                  DATA     0		 R6 VALUE TO CHECK 225,226,227
                  DATA     0		 R7 INCREMENT VALUE 32
                  DATA     0		 R8 INCREMENT VALUE 1
                  DATA     0		 R9
                  DATA     0		 R10   POSITIONS
                  DATA     0		 R11	 1 2 3
                  DATA     0		 R12	 4 5 6
                  DATA     0		 R13	 7 8 9
                  DATA     0		 R14
                  DATA     0		 R15
                  DATA    WRKSPC
                  DATA    SRCH

SRCH          LI          R6,>C700 199 UNARMED TRAP
                  LI          R7,32    UP & DOWN
                  LI          R8,>0100 1 CHAR NUMBER
SRCHL       MOV     R1,R2    POSITION 5
                 S          R7,R2    POSITION 2
                CB        *R2,R6   EQUAL?
               JEQ       CNG	  REPLACE
               DEC       R2	   POSITION 1
   CB	 *R2,R6   EQUAL?
   JEQ    CNG	  REPLACE
   A	  R7,R2    POSITION 4
   CB	 *R2,R6   EQUAL?
   JEQ    CNG	  REPLACE
   A	  R7,R2    POSITION 7
   CB	 *R2,R6   EQUAL?
   JEQ    CNG	  REPLACE
   INC    R2	   POSITION 8
   CB	 *R2,R6   EQUAL?
   JEQ    CNG	  REPLACE
   INC    R2	   POSITION 9
   CB	 *R2,R6   EQUAL?
   JEQ    CNG	  REPLACE
   S	  R7,R2    POSITION 6
   CB	 *R2,R6   EQUAL?
   JEQ    CNG	  REPLACE
   S	  R7,R2    POSITION 3
   CB	 *R2,R6   EQUAL?
   JEQ    CNG	  REPLACE
   CI	 R6,>CF00 FOOD?
   JEQ    HV	   FIND A MOVE
   LI	 R6,>CF00 FOOD 207
   JMP    SRCHL    SEARCH LOOP
CNG    CI	 R6,>C700 199 UNARMED TRAP
   JNE    CNGF	 NO HAS TO BE FOOD
   LI	 R6,>DA00 218 REARM THE TRAP
   MOVB   R6,*R2   REPLACE WITH TRAP
   RTWP		    RETURN DELAY
CNGF   LI	 R6,>8000 SPACE
   MOVB   R6,*R2   REPLACE WITH SPACE

HV	 LI	 R6,>E100 VALUES 225 226 227
HVANG  MOV    R1,R2    POSITION 5
   DEC    R2	   POSITION 4
   CB	 *R2,R6   EQUAL?
   JEQ    GOUT	 YES
   A	  R7,R2    POSITION 7
   CB	 *R2,R6   EQUAL?
   JEQ    GOUT	 YES
   INC    R2	   POSITION 8
   CB	 *R2,R6   EQUAL?
   JEQ    GOUT	 YES
   INC    R2	   POSITION 9
   CB	 *R2,R6   EQUAL?
   JEQ    GOUT	 YES
   S	  R7,R2    POSITION 6
   CB	 *R2,R6   EQUAL?
   JEQ    GOUT	 YES
   S	  R7,R2    POSITION 3
   CB	 *R2,R6   EQUAL?
   JEQ    GOUT	 YES
   DEC    R2	   POSITION 2
   CB	 *R2,R6   EQUAL?
   JEQ    GOUT	 YES	 
   DEC    R2	   POSITION 1
   CB	 *R2,R6   EQUAL?
   JEQ    GOUT	 YES
   AB	 R8,R6    ADD 1
   CI	 R6,>E400 228?
   JEQ    TRAIL    FIND A TRAIL
   JMP    HVANG    LOOP
TRAIL  LI	 R6,>E100 TRAIL?
TRAIL2 LI	 R1,>2022 START OVER!!!!
FIND   INC    R1	   ADD 1 TO COLUMN
   CI	 R1,>3FDD END OF 8K?
   JNE    FIND1
   AB	 R8,R6
   CI	 R6,>E400 228?
   JEQ    GOUT3
   JMP    FIND  
FIND1  CB	 *R1,R6   225? 226? 227?
   JEQ    HV	   RESTART HERE!!!
   JMP    FIND	 NO KEEP LOOKING
GOUT   LI	 R6,>E100 225
GOUT1  CB	 *R1,R6   EQUAL?
   JEQ    GOUT2    YES
   AB	 R8,R6    ADD 1 TO CHARACTER
   CI	 R6,>E300 227?
   JNE    GOUT1    NEXT CHECK
   LI	 R6,>7F00 SET UP FOR SPACE
GOUT2  AB	 R8,R6    ADD 1 TO CHARACTER
   MOVB   R6,*R1   UPDATE OLD CHARATER
   MOV    R2,R1    PUT NEW X IN OLD X
GOUT3  RTWP		    DONE GO BACK TO RXB

   TITL  'FEEL AROUND ROUTINES'
   DATA   WRKSPC
   DATA   FEEL
FEEL   CLR    R0		  FOOD:TRAP
   LI	 R7,32	   UP & DOWN
   MOV    R3,R4	   POSITION 5
   S	  R7,R4	   POSITION 2
   INC    R4		  POSITION 3 SAVED
FEEL1  LI	 R6,>DA00    218 TRAP
   BL	 @FCHK	   CHECK
   C	  R4,R2	   POSITION 3?
   JNE    FEEL1	   LOOP
FEEL2  LI	 R6,>D700    215 WALL
   BL	 @FCHK	   CHECK
   C	  R4,R2	   POSITION 3?
   JNE    FEEL2	   LOOP
FEEL3  LI	 R6,>CF00    207 FOOD
   BL	 @FCHK	   CHECK
   C	  R4,R2	   POSITION 3?
   JNE    FEEL3	   LOOP
   RTWP			   RETURN TO RXB
FCHK   MOV    R3,R2	   POSITION 5
   S	  R7,R2	   POSITION 2
   CB	 *R2,R6	  SAME?
   JEQ    FLIP	    REPLACE
   DEC    R2		  POSITION 1
   CB	 *R2,R6	  SAME?
   JEQ    FLIP	    REPLACE
   A	  R7,R2	   POSITION 4
   CB	 *R2,R6	  SAME?
   JEQ    FLIP	    REPLACE
   A	  R7,R2	   POSITION 7
   CB	 *R2,R6	  SAME?
   JEQ    FLIP	    REPLACE
   INC    R2		  POSITION 8
   CB	 *R2,R6	  SAME?
   JEQ    FLIP	    REPLACE
   INC    R2		  POSITION 9
   CB	 *R2,R6	  SAME?
   JEQ    FLIP	    REPLACE
   S	  R7,R2	   POSITION 6
   CB	 *R2,R6	  SAME?
   JEQ    FLIP	    REPLACE
   S	  R7,R2	   POSITION 3
   CB	 *R2,R6	  SAME?
   JEQ    FLIP	    REPLACE
   RT				 RETURN
FLIP   CI	 R6,>DA00    218 TRAP
   JNE    FLIP1	   NEXT
   LI	 R8,>C700    199 DISARMED
   INC    R0		  ADD 1 TRAP
   JMP    FLIP3	   REPLACE 
FLIP1  CI	 R6,>D700    215 WALL
   JNE    FLIP2	   NEXT
   LI	 R8,>EF00    239 SHOW WALL
   JMP    FLIP3	   REPLACE
FLIP2  CI	 R6,>CF00    207 FOOD
   JNE    FLIP4	   DONE
   LI	 R8,>8000    129 SPACE
   AI	 R0,>0100    ADD 1 FOOD
FLIP3  MOVB   R8,*R2	  REPLACE IT
FLIP4  RT				 RETURN
   END

[matthew180]

I've seen that many times, too, however, that's just sloppiness. Comments are not an afterthought, they are a part of the product. If the person changing the code felt the comments were unnecessary, they should have been removed, not ignored. Then the next person comes along and has to ask "is the code or the comment correct, because I don't know if I just found a bug?"

 

I literally went through that exact scenario in my day job about 3 weeks ago. It took me two weeks to get someone to confirm the "intended behavior". The data structure changed, yet the code did not and the comments explained something completely different from what was happening. Oh, and the original author of the code who wrote it in 2009, they passed away last year...

 

[RXB]

Yea before I retired from Freightliner we had many programs that they laid off the people that wrote it but refused to hire them back to fix the code.

 

So we just had to patch it and hope for the best. We had some Windows 95 Software that no one could figure out how to upgrade it and make it work.

 

The Windows 98SE would not work as something internal in the timing had changed on some of the robots. So they still run Windows 95 only.

[+InsaneMultitasker]

 

I've seen that many times, too, however, that's just sloppiness. Comments are not an afterthought, they are a part of the product.

 

So true. They really can become part of the code to a degree. As the years have gone by I find myself writing high level "comments" first, most frequently in an outline format. I then translate the comments and structure into the instructions necessary for my code. Doing this seems to work well; I can flesh out an algorithm or routine more quickly than my structured by ad hoc "just start coding and comment as you go" method of madness.

[+OLD CS1]

So we just had to patch it and hope for the best. We had some Windows 95 Software that no one could figure out how to upgrade it and make it work.

 

I have had many successes with virtualizing Windows 95 and 98/SE environments into Virtual PC for customers. VirtualBox would probably work as well, if not better for some things. Modern emulation is pretty damned handy.

[TheMole]

Probably not far apart at all. And yes, my examples could have been better if the language supports such constructs (constants, structures, long variable names, etc), but I was partially thinking of languages like ROM BASIC or assembly on a classic computer. Although large blocks of comments don't work so well with BASIC since they consume memory, as do longer variable names.

 

In general though, I prefer to comment first then add the code to do what is described. Then if I need to add comments to specific parts of the code for clarification, the comments have purpose.

 

That's what I love about cross-compilers. You have all the modern tools at your disposal during development, but they have no impact on the outputted code

[TheMole]

I've seen that many times, too, however, that's just sloppiness. Comments are not an afterthought, they are a part of the product. If the person changing the code felt the comments were unnecessary, they should have been removed, not ignored. Then the next person comes along and has to ask "is the code or the comment correct, because I don't know if I just found a bug?"

 

It's not always sloppiness though, remember that a lot of modern IDEs have refactoring tools built-in. They work really well, and can save you a lot of work, but they can't change comments. If I need to change the organization of a struct in a 100kloc project, I'm not wading through the source files manually to do a find-and-replace with visual inspection.

 

All that not to say that stuff doesn't need to be commented, but generally forcing yourself to make the code readable, understandable without comments will help you write better code. As I said before, explaining an algorithm, a clever optimization, unclear pitfalls, etc... is needed, and that's what comments are for. Just use them wisely, and more is definitely not always better.

[Willsy]

All that not to say that stuff doesn't need to be commented, but generally forcing yourself to make the code readable, understandable without comments will help you write better code. As I said before, explaining an algorithm, a clever optimization, unclear pitfalls, etc... is needed, and that's what comments are for. Just use them wisely, and more is definitely not always better.

 

Fully agree. One should strive to make code as self-documenting as possible, meaning the level of commenting can be dialed down a few notches. Then, as you say, in the event of code being re-factored the risk of errant comments is much reduced.

 

There's quite a skill involved which only comes through experience, I guess.

[Tursi]

It's not always sloppiness though, remember that a lot of modern IDEs have refactoring tools built-in. They work really well, and can save you a lot of work, but they can't change comments. If I need to change the organization of a struct in a 100kloc project, I'm not wading through the source files manually to do a find-and-replace with visual inspection.

 

All that not to say that stuff doesn't need to be commented, but generally forcing yourself to make the code readable, understandable without comments will help you write better code. As I said before, explaining an algorithm, a clever optimization, unclear pitfalls, etc... is needed, and that's what comments are for. Just use them wisely, and more is definitely not always better.

 

I can't think of a refactoring case that would change comments whose purpose it is to explain intent or algorithm, though. You shouldn't include code in your intent statements, most of the time. I'm not talking about changing the name of a variable. I'm talking about rewriting a piece of code so that the algorithm no longer matches the comments. The person who did that, should have done something with the comments.

 

Besides, just cause YOU won't wade through the code doesn't mean nobody should.

 

Any /final/ code changes that you submit to a master repository really should be reviewed, even if only a brief scan. If nobody else looks at it, YOU should look at it. That's just being a good citizen. Again, it's not about YOU, it's about making it easier for someone else down the road. A lot of programmers early in their career think the long view is a month or two, it's not. It's ten years out. After you've IPO'd your startup and left the company.

 

Ultimately, I think you and I are on the same page, really. I'm not advocating commenting every line of code either. But comments are /important/ and not something you should strive to eliminate. Doing so is doing a grave disservice to someone down the road. And while you might not care about that, I do (I think you do, too, you're just arguing the other side of a hairline crack that separates our views ).

 

Mark, I'd argue that the desire to eliminate too many comments comes more from inexperience than experience. I've seen it similar transitions from other programmers I've worked with, and I've done it myself. I had a heated discussion in front of the class with my computer programming teacher about "useless comments" 20 years ago. But the more work I do in large teams with a very diverse skill set, the more I value them. With comments you can very quickly take a new piece of code from "what the hell was this guy trying to pull???" to "no, that won't work and here's why", plus you are prepped to help fix it. The experience factor comes down to finding the right balance, but too many comments is rarely worse than too few.

 

Anyway.. that's about all I think on that.

 

[+mizapf]

There is a new paradigm on commenting, as I had to learn recently. But maybe those people just decided to interpret stuff for their own needs.

 

This change comes from the "Agile" people with their "Agile manifesto" which, essentially, in each of its points contradicts to my ideas of good software development, but hey, it's new, and my view may be stone-age in the meantime.

 

http://agilemanifesto.org/

 

One particular point is documentation. I admit that working on bigger projects often requires you to write lots of text that nobody ever reads again. This is especially true for publicly funded, international projects as we have in the EU. I remember one day our group leader said we had to stop coding now, or otherwise we would not be able to complete the deliverable documentation in time.

 

Well, and just some weeks ago I had an argument with one of my students, concerning the documentation of source code for a practical assignment. My request was to suitably document the source code, preferably declaring the functionality of block structures, methods, the semantics of member variables, and so on, using Javadoc style and end-of-line comments where required.

 

And he just refused and said, I could not be serious, requiring to comment code that way. Comments were superfluous, always outdated, and you always should write programs in a way that you can immediately get the meaning from reading the source.

 

It was not meant to be an important work, so we got to a compromise. However, I was a bit surprised that there are people who refuse to comment their code not because of laziness but because they object to commenting as such.

 

I can understand that comments may be unneeded when you can immediately get the meaning from the line, but in many cases I cannot easily understand what is going on when looking at longer portions of code. Also, when functions are called, you usually don't know the exact meaning of the actual parameter without having a quick look at the function signature.

 

MESS is just another example of sparsely documented code. When I have to find out something outside of my own code, I'm first using a debugger, setting a breakpoint to determine the call stack, then I have a look at each file that seems to be involved. The function of my editor that I mostly depend on is the hyper search function so that I can find out where is the file that contains the class definition. As we have C++ here and not Java, finding class definitions is a challenge sometimes. Luckily MESS has been converted from C to C++ some years ago, because things were a LOT more difficult to read with these C macros that tried to mimic classes.

[TheMole]

There is a new paradigm on commenting, as I had to learn recently. But maybe those people just decided to interpret stuff for their own needs.

 

This change comes from the "Agile" people with their "Agile manifesto" which, essentially, in each of its points contradicts to my ideas of good software development, but hey, it's new, and my view may be stone-age in the meantime.

 

http://agilemanifesto.org/

 

Agile is not really something "new", it has been around for more than a decade. I started using it professionally in 2003, and was immediately enamored with it's simple, low-overhead concepts. In most professional environments I know, agile has become the golden standard that replaced the waterfall approach. However, using "agile" to get away with not commenting your code is a cop-out, and you should tell your student that. Agile says nothing about coding style. The rule about documentation is meant to stimulate documenting as you go along (with the recipient of the code/program in mind, as opposed to other developers), instead of focusing on documentation as a separate deliverable. I have yet to see an agile project that does not force a certain coding and commenting style.

[sometimes99er]

I have no comments ...

 

 

100 CALL CLEAR::CALL SCREEN(5)::FOR A=5 TO 12::CALL COLOR(A,16,1)::NEXT A
110 N$="00030C0F30333C3FC0C300000000000000CCCFF0F3FCFF"::FOR A=65 TO 90
120 CALL CHARPAT(A,C$)::PRINT CHR$(A)&CHR$(A+32);::FOR C=0 TO 1:: D$=""
130 FOR R=0 TO 7:$=D$&SEG$(N$,(ASC(SEG$(C$,C+R*2+1,1))-48)*2+1,2)::NEXT R
140 CALL CHAR(A+C*32,D$)::NEXT C::NEXT A::PRINT::PRINT::N$="QUASIPARTICLES"
150 FOR A=1 TO LEN(N$)::PRINT SEG$(N$,A,1)&CHR$(ASC(SEG$(N$,A,1))+32);::NEXT A
160 FOR A=1 TO 28::CALL SPRITE(#A,46,16,1,124,8,RND*10-5)::NEXT A::GOTO 160

Edited August 11, 2017 by sometimes99er

[Retrospect]

I read somewhere on the internet, regarding a TRS-80 Model-1 coder who disliked having to put comments in his code (he was programming a 4K level 1 machine), he said something like "If it was hard to code, it should be hard to read!"

Edited August 9, 2013 by Retrospect