|
This is from another forum I visit once in a while, somebody posting a code snippet:
void loop(){
byte rxbyte; byte temp; rxbyte = serial_getch();
if (rxbyte == 254) {
switch (serial_getch()) {
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. 
|
|
|
|
|
I see not speelign errors! 
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! 
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.
|
|
|
|
|
|
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!
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 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:
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! 
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 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(); }
}
|
|
|
|
|
In general, I agree with you, the exception being concise^Wtoo clever for their own good LINQ expressions like these:
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)
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)) _
})
modified 18-Nov-13 11:32am.
|
|
|
|
|
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.
|
|
|
|
|
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[ ^]
|
|
|
|
|
Fortunately (and this probably explains a lot), the site is for hobbyist coding (this particular code is for running on an Arduino). I'm hoping that the guy who wrote it has a day job as a technical writer or something
|
|
|
|
|
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?
|
|
|
|
|
What's with the scare quotes?
|
|
|
|
|
Ron Beyer wrote: At least we know what the 'compiler' is doing when you declare a variable
Sure, we need certainties, after all!
Veni, vidi, vici.
|
|
|
|
|
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
|
|
|
|
|
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
|
|
|
|
|
All of those can be solved with compiler constants, for example:
#define CMDSTART 254
#define READCMD 1
#define WRITECMD 2
etc... Which also eliminates "magic numbers" and makes the program more maintainable.
|
|
|
|
|
So... I guess, there's a comment like
(yes|no|maybe)*
|
|
|
|
|
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.
|
|
|
|
|
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.
|
|
|
|
|
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...
|
|
|
|
|
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
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
