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 :)
-
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 :)
-
You'd think they'd spell check it. :rolleyes:
I see not speelign errors! :laugh: Mind you, I like the quotes round "compiler" - as if they aren't quite sure it is a compiler, it might be a fridge or something like that... I do rely on spell checkers a lot - I even have a VS extension for string and comment checking - but I like the Chrome one, especially when it picks up grammar problems! :-D
The only instant messaging I do involves my middle finger. English doesn't borrow from other languages. English follows other languages down dark alleys, knocks them over and goes through their pockets for loose grammar.
-
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 real question is where should commenting stop? I have some coworkers who comment .NET functions and classes that we don't use a lot. Especially when it's more complex and intellisense alone won't help you a lot. Just assume we don't use strings a lot. It would be something like:
// A string is used to store some text.
string s = "Hello!";Someone at our company might not know what a string is (after all, we rarely use it (in this example)), so this will save them a quick Google lookup. At the other hand, is it really our job to document .NET classes? Your example is clearly a little too much though! :laugh::thumbsup:
It's an OO world.
public class Sander : Lazy<Person>{
public void DoWork(){ throw new NotImplementedException(); }
} -
The real question is where should commenting stop? I have some coworkers who comment .NET functions and classes that we don't use a lot. Especially when it's more complex and intellisense alone won't help you a lot. Just assume we don't use strings a lot. It would be something like:
// A string is used to store some text.
string s = "Hello!";Someone at our company might not know what a string is (after all, we rarely use it (in this example)), so this will save them a quick Google lookup. At the other hand, is it really our job to document .NET classes? Your example is clearly a little too much though! :laugh::thumbsup:
It's an OO world.
public class Sander : Lazy<Person>{
public void DoWork(){ throw new NotImplementedException(); }
}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 see not speelign errors! :laugh: Mind you, I like the quotes round "compiler" - as if they aren't quite sure it is a compiler, it might be a fridge or something like that... I do rely on spell checkers a lot - I even have a VS extension for string and comment checking - but I like the Chrome one, especially when it picks up grammar problems! :-D
The only instant messaging I do involves my middle finger. English doesn't borrow from other languages. English follows other languages down dark alleys, knocks them over and goes through their pockets for loose grammar.
-
"the the code"
A pure spelling checker wouldn't spot that - you need a grammar checker as each word is correctly spelled. And yes, I missed it completely! :laugh:
The only instant messaging I do involves my middle finger. English doesn't borrow from other languages. English follows other languages down dark alleys, knocks them over and goes through their pockets for loose grammar.
-
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"
