Over-documentation
-
This is from another forum I visit once in a while, somebody posting a code snippet:
void loop(){
byte rxbyte; //this tells the 'compiler' to allocate some memory for a variable called rxbyte
byte temp; //this tells the 'compiler' to allocate some memory for a variable called temp
rxbyte = serial_getch(); //this calls the 'function' serial_getch(), stores result in rxbyteif (rxbyte == 254) //Matrix uses 254 for commands, if rxbyte = 254 the the code below runs
{
switch (serial_getch()) //calls serial_getch() to get the next byte from the PC
// 'switches' based on that byte
{And it continues on like that. At least we know what the 'compiler' is doing when you declare a variable :)
Are there incentives based on code file size wherever this guy works? I can write brilliant stories and make insane money then. Seriously, this is painful. If one needs this much commenting to understand what the code does, he should rather stay away from it.
"Bastards encourage idiots to use Oracle Forms, Web Forms, Access and a number of other dinky web publishing tolls.", Mycroft Holmes[^]
-
I would say if the people working on your code can't put the caret in the middle of "string" (or whatever you are using) and hit F1 to read the MSDN documentation, they probably shouldn't be messing around in the code base. There are a lot of theories about how to document code, and here's mine: 1. Classes, methods, and properties (public especially, but all really), should be documented using the built-in /// method, with at least the summary and parameter explanations, remarks should be added if there is more, and document the exceptions that the method throws. This makes the other developers life easier (in Intellisense and later when you generate API documentation) to understand what a class/method/property is for. 2. Internal documentation (inside methods), generally skip it. There are three (main) reasons why somebody would document inside a function, (a) its complicated or (b) its long. If either of these are the case, it should be refactored. If the purpose of the function is sufficiently documented and the developer is qualified to work on it, the interior doesn't need to be documented. (There are of course rare exceptions, such as documenting bug work-arounds which if the developer didn't have knowledge of the bug, the code wouldn't make sense). The other reason (c) why people put comments in functions is generally white-noise. They are documenting the thought process which is unnecessary. A proper description of the input/output of the function and it being correctly "factored" shouldn't require knowing the developers thought process as they wrote it. When you see that they are probably doing "design by code", or "code-first", I won't get into that... I used to be in the school of "every line should be documented", but I learned that really the comments where only there for the sake of writing the code, when I was debugging it I never looked at the comments again. It was more of "thinking out loud" than anything. Since adopting my method, I write cleaner, less cluttered code...
I have some thoughts on commenting as well. I even wrote a tip about it. Write comments that matter[^], you might like it :)
It's an OO world.
public class Sander : Lazy<Person>{
public void DoWork(){ throw new NotImplementedException(); }
} -
Are there incentives based on code file size wherever this guy works? I can write brilliant stories and make insane money then. Seriously, this is painful. If one needs this much commenting to understand what the code does, he should rather stay away from it.
"Bastards encourage idiots to use Oracle Forms, Web Forms, Access and a number of other dinky web publishing tolls.", Mycroft Holmes[^]
-
This is from another forum I visit once in a while, somebody posting a code snippet:
void loop(){
byte rxbyte; //this tells the 'compiler' to allocate some memory for a variable called rxbyte
byte temp; //this tells the 'compiler' to allocate some memory for a variable called temp
rxbyte = serial_getch(); //this calls the 'function' serial_getch(), stores result in rxbyteif (rxbyte == 254) //Matrix uses 254 for commands, if rxbyte = 254 the the code below runs
{
switch (serial_getch()) //calls serial_getch() to get the next byte from the PC
// 'switches' based on that byte
{And it continues on like that. At least we know what the 'compiler' is doing when you declare a variable :)
I've read about paying developers for the number of lines in their code files. But he does not use an extra line for the comment. Does he get paid by character?
-
This is from another forum I visit once in a while, somebody posting a code snippet:
void loop(){
byte rxbyte; //this tells the 'compiler' to allocate some memory for a variable called rxbyte
byte temp; //this tells the 'compiler' to allocate some memory for a variable called temp
rxbyte = serial_getch(); //this calls the 'function' serial_getch(), stores result in rxbyteif (rxbyte == 254) //Matrix uses 254 for commands, if rxbyte = 254 the the code below runs
{
switch (serial_getch()) //calls serial_getch() to get the next byte from the PC
// 'switches' based on that byte
{And it continues on like that. At least we know what the 'compiler' is doing when you declare a variable :)
-
I would say if the people working on your code can't put the caret in the middle of "string" (or whatever you are using) and hit F1 to read the MSDN documentation, they probably shouldn't be messing around in the code base. There are a lot of theories about how to document code, and here's mine: 1. Classes, methods, and properties (public especially, but all really), should be documented using the built-in /// method, with at least the summary and parameter explanations, remarks should be added if there is more, and document the exceptions that the method throws. This makes the other developers life easier (in Intellisense and later when you generate API documentation) to understand what a class/method/property is for. 2. Internal documentation (inside methods), generally skip it. There are three (main) reasons why somebody would document inside a function, (a) its complicated or (b) its long. If either of these are the case, it should be refactored. If the purpose of the function is sufficiently documented and the developer is qualified to work on it, the interior doesn't need to be documented. (There are of course rare exceptions, such as documenting bug work-arounds which if the developer didn't have knowledge of the bug, the code wouldn't make sense). The other reason (c) why people put comments in functions is generally white-noise. They are documenting the thought process which is unnecessary. A proper description of the input/output of the function and it being correctly "factored" shouldn't require knowing the developers thought process as they wrote it. When you see that they are probably doing "design by code", or "code-first", I won't get into that... I used to be in the school of "every line should be documented", but I learned that really the comments where only there for the sake of writing the code, when I was debugging it I never looked at the comments again. It was more of "thinking out loud" than anything. Since adopting my method, I write cleaner, less cluttered code...
In general, I agree with you, the exception being concise^Wtoo clever for their own good LINQ expressions like these:
' enumerate Future Queries (go to DB in one request), put resulting KatalogIds into HashSets
Dim katalogErrorResults As Dictionary(Of KatalogErrorType, HashSet(Of Int32?))
katalogErrorResults = katalogErrorFutures _
.AsEnumerable() _
.Select(Function(katErr) _
New KeyValuePair(Of KatalogErrorType, HashSet(Of Int32?)) _
(katErr.Key, katErr.Value.ToHashSet)) _
.ToDictionary(Of KatalogErrorType, HashSet(Of Int32?)) _
(Function(kvp) kvp.Key, Function(kvp) kvp.Value, katalogErrorTypeComparer)' transform results to Dictionary(Of Int32?, KatalogErrorDTO)
Return katalogeIds.ToDictionary(
Function(sourceKatId) sourceKatId,
Function(sourceKatId) New KatalogErrorDTO() With { _
.ArtikelNummerPrefix = artikelNummerPrefix,
.SearchQuery = searchquery,
.Errors = [Enum].GetValues(GetType(KatalogErrorType)) _
.Cast(Of KatalogErrorType) _
.ToDictionary(Function(kErrorType) kErrorType, _
Function(kErrorType) katalogErrorResults(kErrorType) _
.Contains(sourceKatId)) _
}) -
In general, I agree with you, the exception being concise^Wtoo clever for their own good LINQ expressions like these:
' enumerate Future Queries (go to DB in one request), put resulting KatalogIds into HashSets
Dim katalogErrorResults As Dictionary(Of KatalogErrorType, HashSet(Of Int32?))
katalogErrorResults = katalogErrorFutures _
.AsEnumerable() _
.Select(Function(katErr) _
New KeyValuePair(Of KatalogErrorType, HashSet(Of Int32?)) _
(katErr.Key, katErr.Value.ToHashSet)) _
.ToDictionary(Of KatalogErrorType, HashSet(Of Int32?)) _
(Function(kvp) kvp.Key, Function(kvp) kvp.Value, katalogErrorTypeComparer)' transform results to Dictionary(Of Int32?, KatalogErrorDTO)
Return katalogeIds.ToDictionary(
Function(sourceKatId) sourceKatId,
Function(sourceKatId) New KatalogErrorDTO() With { _
.ArtikelNummerPrefix = artikelNummerPrefix,
.SearchQuery = searchquery,
.Errors = [Enum].GetValues(GetType(KatalogErrorType)) _
.Cast(Of KatalogErrorType) _
.ToDictionary(Function(kErrorType) kErrorType, _
Function(kErrorType) katalogErrorResults(kErrorType) _
.Contains(sourceKatId)) _
})Some LINQ queries are more like when people first discover the ? : conditional operator and you start seeing nested inline conditionals like firstvar == somevalue ? ((myvalue1 + 10) <= 4 ? : false : true) : false Or something worse than that. Your query above could be refactored to be much more clear, therefore removing the need for concise comments. If the above were broken down into individual lines (instead of using a new line and the "."), along with not inline defining the function, it would be easy to understand, and even easier to debug. This is where my problem with "fluent" language extensions come in, while fluent reads more like English, the formatting/extras required to get it to look that way generally obscures the intent.
-
This is from another forum I visit once in a while, somebody posting a code snippet:
void loop(){
byte rxbyte; //this tells the 'compiler' to allocate some memory for a variable called rxbyte
byte temp; //this tells the 'compiler' to allocate some memory for a variable called temp
rxbyte = serial_getch(); //this calls the 'function' serial_getch(), stores result in rxbyteif (rxbyte == 254) //Matrix uses 254 for commands, if rxbyte = 254 the the code below runs
{
switch (serial_getch()) //calls serial_getch() to get the next byte from the PC
// 'switches' based on that byte
{And it continues on like that. At least we know what the 'compiler' is doing when you declare a variable :)
-
This is from another forum I visit once in a while, somebody posting a code snippet:
void loop(){
byte rxbyte; //this tells the 'compiler' to allocate some memory for a variable called rxbyte
byte temp; //this tells the 'compiler' to allocate some memory for a variable called temp
rxbyte = serial_getch(); //this calls the 'function' serial_getch(), stores result in rxbyteif (rxbyte == 254) //Matrix uses 254 for commands, if rxbyte = 254 the the code below runs
{
switch (serial_getch()) //calls serial_getch() to get the next byte from the PC
// 'switches' based on that byte
{And it continues on like that. At least we know what the 'compiler' is doing when you declare a variable :)
Ron Beyer wrote:
At least we know what the 'compiler' is doing when you declare a variable
Actually, it's not even accurate, technically. The compiler doesn't allocate "some memory", it reserves space on the stack when the function is called. Yes, the stack is of course memory, but it's not the same kind of memory one uses when allocating / deallocating. Marc
-
This is from another forum I visit once in a while, somebody posting a code snippet:
void loop(){
byte rxbyte; //this tells the 'compiler' to allocate some memory for a variable called rxbyte
byte temp; //this tells the 'compiler' to allocate some memory for a variable called temp
rxbyte = serial_getch(); //this calls the 'function' serial_getch(), stores result in rxbyteif (rxbyte == 254) //Matrix uses 254 for commands, if rxbyte = 254 the the code below runs
{
switch (serial_getch()) //calls serial_getch() to get the next byte from the PC
// 'switches' based on that byte
{And it continues on like that. At least we know what the 'compiler' is doing when you declare a variable :)
Lovely Not only way over the top, but where comments would be useful, those comments aren't. I would only put 1 comment in there - //254 means we are about to process a command, so read one & process it. Plus a comment to add a description of each entry in the switch statement to translate the number into something sensible. This removes clutter, and also the need to look up op-codes in the event of brain-fade. Regards, Stewart
-
Lovely Not only way over the top, but where comments would be useful, those comments aren't. I would only put 1 comment in there - //254 means we are about to process a command, so read one & process it. Plus a comment to add a description of each entry in the switch statement to translate the number into something sensible. This removes clutter, and also the need to look up op-codes in the event of brain-fade. Regards, Stewart
-
This is from another forum I visit once in a while, somebody posting a code snippet:
void loop(){
byte rxbyte; //this tells the 'compiler' to allocate some memory for a variable called rxbyte
byte temp; //this tells the 'compiler' to allocate some memory for a variable called temp
rxbyte = serial_getch(); //this calls the 'function' serial_getch(), stores result in rxbyteif (rxbyte == 254) //Matrix uses 254 for commands, if rxbyte = 254 the the code below runs
{
switch (serial_getch()) //calls serial_getch() to get the next byte from the PC
// 'switches' based on that byte
{And it continues on like that. At least we know what the 'compiler' is doing when you declare a variable :)
-
"the the code"
-
The first time I saw something like that said "Paris in the / the spring". I saw this[^] sign a couple of weeks ago at http://en.wikipedia.org/wiki/Painted_Rocks_(Arizona)[^]
-
This is from another forum I visit once in a while, somebody posting a code snippet:
void loop(){
byte rxbyte; //this tells the 'compiler' to allocate some memory for a variable called rxbyte
byte temp; //this tells the 'compiler' to allocate some memory for a variable called temp
rxbyte = serial_getch(); //this calls the 'function' serial_getch(), stores result in rxbyteif (rxbyte == 254) //Matrix uses 254 for commands, if rxbyte = 254 the the code below runs
{
switch (serial_getch()) //calls serial_getch() to get the next byte from the PC
// 'switches' based on that byte
{And it continues on like that. At least we know what the 'compiler' is doing when you declare a variable :)
Amusingly, that doesn't really tell us much - the compiler doesn't "allocate" memory, the stack is allocated when the program starts - this simply updates stack pointers.
"If you don't fail at least 90 percent of the time, you're not aiming high enough." Alan Kay.
-
This is from another forum I visit once in a while, somebody posting a code snippet:
void loop(){
byte rxbyte; //this tells the 'compiler' to allocate some memory for a variable called rxbyte
byte temp; //this tells the 'compiler' to allocate some memory for a variable called temp
rxbyte = serial_getch(); //this calls the 'function' serial_getch(), stores result in rxbyteif (rxbyte == 254) //Matrix uses 254 for commands, if rxbyte = 254 the the code below runs
{
switch (serial_getch()) //calls serial_getch() to get the next byte from the PC
// 'switches' based on that byte
{And it continues on like that. At least we know what the 'compiler' is doing when you declare a variable :)
Over-zealous on the documentation part but missed out some basic coding standards like below: 1) Magic Strings/Numbers in code. 2) It would be better to have the value of serial_getch() assigned in a variable and then used in switch instead of calling it directly as a function in the switch construct.
Vasudevan Deepak Kumar Personal Homepage You can not step into the same river twice.
-
This is from another forum I visit once in a while, somebody posting a code snippet:
void loop(){
byte rxbyte; //this tells the 'compiler' to allocate some memory for a variable called rxbyte
byte temp; //this tells the 'compiler' to allocate some memory for a variable called temp
rxbyte = serial_getch(); //this calls the 'function' serial_getch(), stores result in rxbyteif (rxbyte == 254) //Matrix uses 254 for commands, if rxbyte = 254 the the code below runs
{
switch (serial_getch()) //calls serial_getch() to get the next byte from the PC
// 'switches' based on that byte
{And it continues on like that. At least we know what the 'compiler' is doing when you declare a variable :)
Probably he had a boss who complained about insufficient comments - like my boss often does when reviewing my code complains about missing annotations (just review annotations, the code was already commented properly). So I did more or less the same like our guy here - and my boss was happy. He didn't get that it was supposed to be ironic...
-
This is from another forum I visit once in a while, somebody posting a code snippet:
void loop(){
byte rxbyte; //this tells the 'compiler' to allocate some memory for a variable called rxbyte
byte temp; //this tells the 'compiler' to allocate some memory for a variable called temp
rxbyte = serial_getch(); //this calls the 'function' serial_getch(), stores result in rxbyteif (rxbyte == 254) //Matrix uses 254 for commands, if rxbyte = 254 the the code below runs
{
switch (serial_getch()) //calls serial_getch() to get the next byte from the PC
// 'switches' based on that byte
{And it continues on like that. At least we know what the 'compiler' is doing when you declare a variable :)
No horror here if it was posted to someone who's not into programming. E.g. "==" operator is not obvious and may provoke questions what does it mean. Also, telling about "allocating" memory is more understandable that introducing to how stack and pointers work.
Greetings - Jacek
