Documentation of (only) source code

[elias001]

Wait, pseudocode is consider as legitimate form of comment. It is taught and discussed in everybody on algorithms, data structures and discrete mathematics. After more comments, I am getting the impression that between english language comments vs pseudocode, pseudocode is not preferred.

 

[jedishrfu]

Things discussed in your courses don't always reflect the reality of professional programmers and the stress they are under to meet schedules, deadlines, and fix test team defects...

 

[Mark44]

1. If the comments are sufficently succinct and well thought out, they will need updating less, if ever. (A function will generally not change so much that a one or two line properly-written comment will need to be changed.)
2. It is faster and easier, and therefore (at least somewhat) more likely that short comments will get updated as opposed to having to re-write a block of pseudocode.

Regarding #1, the function's basic purpose likely won't change much, but there is more that should be stated in comments than a brief description of what the function's purpose is. For example, it's very possible that the certain parameter values can cause unwanted behavior, and this should be documented, including which values are valid or not allowed. Also, the possible return values should be commented

Regarding #2, I agree, with the stipulation that comments should not be too short, for the reasons stated above.

Wait, pseudocode is consider as legitimate form of comment. It is taught and discussed in everybody on algorithms, data structures and discrete mathematics.

But none of these are applicable to real-world applications programming or systems programming. IMO, the proper place for pseudocode is as a starting point for implementing the final code.

 

[Filip Larsen]

Wait, pseudocode is consider as legitimate form of comment. It is taught and discussed in everybody on algorithms, data structures and discrete mathematics. After more comments, I am getting the impression that between english language comments vs pseudocode, pseudocode is not preferred.

For implementation comments that only or mostly consisting of pseudo-code to make sense I would think that 1) the original pseudo-code algorithm is documented in full at the top of the module (or in the spec), 2) each psedo-code comment used later refer exactly to a line of this code, either by explicit line numbers or an exact copy of the pseudo-code line the follow actual code corresponds to. So in this case the pseudo-code comment act as a kind of index to what part of the the algorithm the code corresponds to.

What I would expect not to work well in general code is to explain every one or two lines of actual code with a pseudo-code "summary", mainly because the pseudo-code don't really convey intent very well so in effect you would explain only the desired effect of the code by a slightly more abstract (but possibly ambiguous) notation.

This doesn't mean that a nice pseudo-code comment here and there can be helpful in combination with "normal" comments describing assumptions and intent, but I would be very skeptical if only pseudo-code is used; to repeat my earlier position: if the code is so unreadable that someone feel a peudo-code comment helps, then make the code more readable and easy to understand instead; if the code already is readable with straight forward semantics then why have a pseudo-code comment at all (unless, as mentioned, it is just a reference to where in an algorithm we are).

 

[FactChecker]

All of this depends on the software development environment that you are working in. If strict configuration management principles are followed, any code change will have associated change requests, change documentation, change reviews, etc. Changing the code without changing the comments to match would not be acceptable.

 

[DaveC426913]

Wait, pseudocode is consider as legitimate form of comment.

And so it is.

But now we're discussing the finer points of its efficacy and pitfalls.

Legitimate doesn't necessarily mean 'best', or 'best in all circumstances' or 'practical in-the-wild'.

 

[FactChecker]

Wait, pseudocode is consider as legitimate form of comment. It is taught and discussed in everybody on algorithms, data structures and discrete mathematics. After more comments, I am getting the impression that between english language comments vs pseudocode, pseudocode is not preferred.

IMO, there is no official definition of where "pseudocode" ends and good comments begin. Books and academic discussions about algorithms may never go farther than the pseudocode, but that does not necessarily make it adequate for commenting final code.
I think of pseudocode as a good first step in writing code by describing the algorithm that code will use. And it might as well be left as comments. But I have not seen it described as adequate comments for the final result. Some might be, but don't count on it.

 

[elias001]

@@FactChecker The reason I so concentrare on pseudocode also has to do with the introduction to Algorithms text by Thomas Cormen, et al. When CS was getting popular to super popular in the 2000s, I heard that if one wants to work in tech at those big tech companies in silicon valley, one can expect questions literally from that textbook or questions referencing that textbook in the technical portion of the job interview. in that book, pseudocode is used so that the algorithms' description are programming language independent.

Like I said in previous posts, commenting within source code was mentioned as a requirement in programming courses, but it was never really shown how is properly done or if there is a proper format that needs to be adhere to. Basically, studebts are left to figure it out for themseles. So I thought well there is a well defined convention for how pseudocode is written. Can't students just use that instead.

 

[FactChecker]

@@FactChecker The reason I so concentrare on pseudocode also has to do with the introduction to Algorithms text by Thomas Cormen, et al. When CS was getting popular to super popular in the 2000s, I heard that if one wants to work in tech at those big tech companies in silicon valley, one can expect questions literally from that textbook or questions referencing that textbook in the technical portion of the job interview.

I am not familiar with that book. There might be a more modern one now. I wouldn't expect exact questions from any text, but I haven't been job-hunting since Biblical times. ;-)

in that book, pseudocode is used so that the algorithms' description are programming language independent.

That sounds OK. It describes the algorithm in a language agnostic way. But the details of implementation in a particular language and/or application is likely to require more details that should be in the comments.

Like I said in previous posts, commenting within source code was mentioned as a requirement in programming courses, but it was never really shown how is properly done or if there is a proper format that needs to be adhere to. Basically, studebts are left to figure it out for themseles. So I thought well there is a well defined convention for how pseudocode is written. Can't students just use that instead.

I wouldn't expect any uniform requirements in the general public. If you work for a military contractor, there may be military standards. In any case, you should expect any large multi-programmer project to have some (possibly unique) project standards for satisfactory documentation.

 

[elias001]

@FactChecker @Filip Larsen @jedishrfu the software engineering stackexchange post i previously referred to is here. More than a few of the initial responses there, I felt like I tossed a small bush fire into a yellow jacket hornets nest. Then it just hit me, wait why don't I use pseudocode since everyone who learned programming in college have came across pseudocode. Also the algorithms book i referred to is Introduction to Algorithms by Thomas H Cormen, Charles E Leiserson and Ronald L Rivest.

 

[harborsparrow]

There is a lot of wisdom in many of the above comments.

My two cents is, don't go overboard. Code documentation ought not be a design doc, though people may feel falsely reassured by the presence of a lot of verbiage.

Code documentation exists to assist future code maintainers in understanding the code in the fewest words possible. Consistent use of a good naming convention can be considered a form of documentation, and also modest block headers. Inline code comments are needed only to specify anything likely to be obscure or never seen before by a coder, or possibly to explain changes made to existing code. And also a brief external document intro with a (hopefully not too complex) diagram.

Overdocumenting can actually be counterproductive.The code does what it does, and that will ideally be self evident--if the coder has tried to make it so. Not all programmers are so nice; instead, they sometimes use the most obscure abbreviated syntax that invokes multiple operations that only someone steeped in that language would know without looking it up,

Maintaining old code, in fact, caused me to modify a number of things about how I wrote and documented new code. I learned many pitfalls to avoid, and I often found old documentation that was out of sync with what the code currently did. As others here have said, it would sometimes have been better to have no documentation in those cases, because the docs themselves need maintaining. It's like in databases: do not duplicate data, for it WILL get out of sync.

When working on an existing code base, I always document changes inline, and maybe sign and date the change as well, to make it easier for the next programmer coming along.

Also, it doesn't hurt to have fun with it. I once found, buried in a long stringy routine, a comment from my predecessor that said, "Oh, and have I said that Visual Basic sucks?" Since it made me laugh, I considered it a very helpful comment.