Programming Question
-
I see nothing wrong with this approach. I work in scientific computing and rarely see commented code. I do not comment my own code. I used to work with Microsoft Dynamics, nothing was commented. IIRC when working with the Source Engine or UT2004 in GD none of the source code had comments. Any comments I have ever seen have simply reflected what was obvious from the function name. If you can't read code how are you doing your job? Naming convention is far more important and far less intrusive. Good documentation in my opinion is far more helpful. If you want to comment use hyperlinks to electronic documentation.
Xittenn wrote:
Good documentation in my opinion is far more helpful.
Do you work in a shop where documentation is manually generated? /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
-
"My code doesn't need comments because it is self documenting, all methods are small and have single functionality, and any business documentation should be provided by the specification and not the code." Discuss.
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
There's a lot to be said for the idea of self-documenting code... not all of it pleasant. The thing is that, while the code may well document itself perfectly in the mind of its creator, that creator might fail to take into account that many people are not exactly what one might describe as "autodidactic" and thus that self-documentation may well be lost on them. Of course, in a perfect world, people who are unable to understand your code shouldn't be playing with it in the first place... but it's not a perfect world, and ultimately, one has to live with the knowledge that from the moment one's code hits a live environment, the catharsis of creating such brilliance is over, and at that point it becomes prostitution, with the nature of a free-for-all built in. Code is self-documenting only if people of at least as high an intelligence as the original programmer are looking at it... but since every programmer (in his own mind, at least) is more intelligent than every other programmer, that's almost guaranteed not to happen. My personal style is to comment at the start of procedures: "This procedure does [this], and (sometimes) here's the algorithm, rendered down into English for all you lesser mortals to understand." I might occasionally document a flag or something which is being used in a particularly abstruse way (consider, for example, the "reverse" or "multiply" - or whatever you want to call it - flag in some implementations of the Luhn algorithm for calculating checksums in credit card numbers -- that's not obvious at all). Sometimes, the way an algorithm works isn't obvious even though the code itself is amazingly simple: for example, to describe why Euclid's algorithm (for the greatest common divisor of two positive integers) works takes pages and pages of text, involving graphs and discussions of where points converge and so on - even though a function for it looks like this: int GCD(int x, int y) { if ((x==0) || (y==0)) return 0; while (x!=y) if (x>y) x-=y; else y-=x; return x; } So in summary, then, I don't think code can always be said to be self-documenting: if the algorithm itself is abstruse (as is Euclid's algorithm) then no matter how simple the code is, the thing's still going to need to be explained. In cases like Euclid's algorithm, the best documentation may well be a link to a
-
"My code doesn't need comments because it is self documenting, all methods are small and have single functionality, and any business documentation should be provided by the specification and not the code." Discuss.
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
Hi i usually prefer self documenting code, but i write comments in the following cases: 1.- I'm writing an API that will be used by someone else 2.- The code refers to bussiness logic 3.- I'm doing something in a non standard way, usually this comes along with an explanation of why i'm doing it. 4.- I'm implementing a workaround 5.- A piece of code was particularly hard to find or figure it out.
CEO at: - Rafaga Systems - Para Facturas - Modern Components for the moment...
-
I am more of an adherent to the "comments are bad" brigade, so will offer a counter view. To be more precise I agree more with the statement that "all comments are apologies [for not making the code self documenting]". I do like statements of intent, not implementation. In the example given, I like the function comment, it states the intent and required preconditions.
///
/// Calculate the tax, taking into account the fine passed.
/// Requires that the tax rate is retrievable from the TaxService
///Whereas the following two appear to me to be worthless and merely clutter up the code. I can tell the first line is getting the tax rate, by the call to the self documenting function, and I know the rest is calculating the value because it is obviously a calculation and it corresponds with what the statement of intent in the function documentation was.
// Get the tax rate using the appropriate service
double taxRate = GetTaxRate();
// calculate the fineComments like the above make code harder to read IMO just due to volume of text. More importantly they are often not updated perfectly when code is maintained, especially when scripted edits are performed; I have been misled in the past by reading the comments and the two not corresponding and this has cost me time, so I would prefer to just read the code and not be distracted. Also where they are a repeat of the code they fail the DRY principle. Like yourself I do write comments during the process of implementation, if I want to sketch out some pseudo code in a comment then slowly turn it into code (just in case I win the lottery and someone else has to finish it off). The difference for me is that once I have finished the code, the comments will have been almost entirely replaced by the code.
I agree with this sentiment. Further, I feel compelled to comment when there is a pitfall to avoid. /// /// Calculate the tax, taking into account the fine passed. /// Requires that the tax rate is retrievable from the TaxService /// /// Note that we subscribe to a service (CheapTax) that may return an /// undocumented -9999.0 as an error value. Be sure to check for this /// value before continuing. /// double taxRate = GetTaxRate();
-
That's "cow-orker".
-
"My code doesn't need comments because it is self documenting, all methods are small and have single functionality, and any business documentation should be provided by the specification and not the code." Discuss.
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
-
"My code doesn't need comments because it is self documenting, all methods are small and have single functionality, and any business documentation should be provided by the specification and not the code." Discuss.
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
To continue... "Naturally, I'm not programming anything that requires more thought than a payroll program, and I have a perfect memory and everyone I work with does too, and all of them plan to live forever and never leave my company." 'nuff said.
"Seize the day" - Horace "It's not what he doesn't know that scares me; it's what he knows for sure that just ain't so!" - Will Rogers, said by him about Herbert Hoover
-
"My code doesn't need comments because it is self documenting, all methods are small and have single functionality, and any business documentation should be provided by the specification and not the code." Discuss.
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
-
No I'm not kidding. Brazen statements, designed to invoke a response outside the area of the question, are flame. You're tagged. The old article to which you refer, does not relate to the question at hand. I know that a missing comma also caused a NASA mishap. But that is beside the point. We are discussing comments. I have publically espoused that comments be minimized. Not eliminated. They are to be replaced by well conceived identifiers drawn from the functional area (other than perhaps i, j, k, etc, when used as indexers). The example, to which you referred, replaced the identifier a with the identifier average_ship_speed. Personally, I find that improved readability immensely. Too often we forget that a failure to provide readable code is a failure to provide maintainable code. Referencing outsourcing, I write code in English. Not because I am an elitist but rather because I speak English as my first language. All of my outsourcing experiences have been with providers who also speak English, but not as their first language. So I tend to review their code and make global changes where misspellings have occurred. But I hold them to the same standard to which I hold myself.
Gus Gustafson
Hey Gus, I think you're missing my point - that there is always scope for confusion in even the simplest, seemingly "safest" code - but I do appreciate the back-and-forth. However, I must take exception when you say my response is outside the area of question. The original post stated "My code doesn't need comments because it is self documenting" which is an argument I've seen again and again. My reply to you, specifically, was that even something as simple as
average_ship_speedcan cause problems, especially when two different people using two different system (eg Metric and Imperial) consume the same value and have different expectations.gggustafson wrote:
I tend to review their code and make global changes where misspellings have occurred. But I hold them to the same standard to which I hold myself.
That's important, but with spell-checkers readily available I've found that the biggest issue is not spelling, but rather meaning. I'm sure you read my blog post that discusses the issues with that. Overall I do agree that comments are not a replacement for good coding, and I also feel that good coding cannot be a replacement for good comments. Their is so often scope for ambiguity and even with the best devs I come across problems again and again.
cheers, Chris Maunder The Code Project | Co-founder Microsoft C++ MVP
-
It was unitless :)
Gus Gustafson
I have a friend who enjoys quoting things like this in furlongs per lunar month.
cheers, Chris Maunder The Code Project | Co-founder Microsoft C++ MVP
-
At best, self documenting code can only ever document what the code does, not what it was intended to do. The differences between the two are generally referred to as "bugs".
Yeah, exactly. I'm starting to think that this whole "I don't need to use comments" thing is coming from people misunderstanding what self-documenting code is. Self-documenting code is largely about readability (which is good); it doesn't mean that you never need to use comments. Self-documenting code can reduce the need for comments, but that's not the same as eliminating the need for comments. Whenever I hear programmers making these kinds of over-generalized dogmatic statements, I assume it to be a sign of lack of experience in real-world programming, because I can't imagine how someone can program for years and not run into counterexamples.
-
Hey Gus, I think you're missing my point - that there is always scope for confusion in even the simplest, seemingly "safest" code - but I do appreciate the back-and-forth. However, I must take exception when you say my response is outside the area of question. The original post stated "My code doesn't need comments because it is self documenting" which is an argument I've seen again and again. My reply to you, specifically, was that even something as simple as
average_ship_speedcan cause problems, especially when two different people using two different system (eg Metric and Imperial) consume the same value and have different expectations.gggustafson wrote:
I tend to review their code and make global changes where misspellings have occurred. But I hold them to the same standard to which I hold myself.
That's important, but with spell-checkers readily available I've found that the biggest issue is not spelling, but rather meaning. I'm sure you read my blog post that discusses the issues with that. Overall I do agree that comments are not a replacement for good coding, and I also feel that good coding cannot be a replacement for good comments. Their is so often scope for ambiguity and even with the best devs I come across problems again and again.
cheers, Chris Maunder The Code Project | Co-founder Microsoft C++ MVP
FYI, knots
Gus Gustafson
-
To continue... "Naturally, I'm not programming anything that requires more thought than a payroll program, and I have a perfect memory and everyone I work with does too, and all of them plan to live forever and never leave my company." 'nuff said.
"Seize the day" - Horace "It's not what he doesn't know that scares me; it's what he knows for sure that just ain't so!" - Will Rogers, said by him about Herbert Hoover
Lol. Speaking as someone who has worked on a number of different payroll programs, I can assure you that they do require a great deal of thought!
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
-
Xittenn wrote:
Good documentation in my opinion is far more helpful.
Do you work in a shop where documentation is manually generated? /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
Your question is a little vague given my examples. When you say shop I am assuming industrial and related to my Dynamics comment. We did generate our 'documentation' both manually and automatically. Stepping away from the industrial concept and into scientific research, all my documentation is generated manually(I would imagine the same would hold in a game studio.) In science it's about solvers and these tend to be complex entities that are not readily documented by any automated techniques that I am aware of(do enlighten.) Again your question is a little vague(from my perspective,) I'm not entirely sure what you were expecting as a response.
-
Your question is a little vague given my examples. When you say shop I am assuming industrial and related to my Dynamics comment. We did generate our 'documentation' both manually and automatically. Stepping away from the industrial concept and into scientific research, all my documentation is generated manually(I would imagine the same would hold in a game studio.) In science it's about solvers and these tend to be complex entities that are not readily documented by any automated techniques that I am aware of(do enlighten.) Again your question is a little vague(from my perspective,) I'm not entirely sure what you were expecting as a response.
Xittenn wrote:
When you say shop I am assuming industrial
shop == software development team
Xittenn wrote:
all my documentation is generated manually(I would imagine the same would hold in a game studio.)
Bad assumption. :) All our API documentation is generated automatically. Just like the .NET, Java and Android APIs. /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
-
Xittenn wrote:
When you say shop I am assuming industrial
shop == software development team
Xittenn wrote:
all my documentation is generated manually(I would imagine the same would hold in a game studio.)
Bad assumption. :) All our API documentation is generated automatically. Just like the .NET, Java and Android APIs. /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
I see you have a very firm stance on your coding techniques and best practices, and I get the strong feeling that you do not appreciate the alternative. My original post was not intended to dissuade, but I really don't like some of the overly eager approaches being taken by certain 'shops' and where it is in turn expected that my 'shop' hold these same values. If I were to come into a situation where inlined comments allowed an automation process to produce clear documentation--and this was the best solution--I would post this as well. To date I have not! And again, not too sound as though this is standard across the board, but of all the code I've worked with the standards seemed pretty much the same. I'm kind of bothered how the first quote you made was abbreviated out of its original context. Not every 'shop'--as you put it--is an agile code tank, and that was my point.
-
I think comments are worth their weight so ling as they are written well - describing the business reasons not the technology (unless the tech is crafty, unusual or complex) when I sit down to write a method, I start by calling it something
public double CalculateTax(double fine)
{
}Then I comment it
///
/// Calculate the tax, taking into account the fine passed.
/// Requires that the tax rate is retrievable from the TaxService
///Then I might write some test code just to get it building
///
/// Calculate the tax, taking into account the fine passed.
/// Requires that the tax rate is retrievable from the TaxService
///
public double CalculateTax(double fine)
{
// TODO: Perform the tax calculation
return 34567.89;
}Then I start to flesh out the method by way of comments
///
/// Calculate the tax, taking into account the fine passed.
/// Requires that the tax rate is retrievable from the TaxService
///
public double CalculateTax(double fine)
{
// Get the tax rate using the appropriate service
// calculate the fine (I think it is just fine * tax rate but need to check with spec!)
}Then, finally, I write the code
///
/// Calculate the tax, taking into account the fine passed.
/// Requires that the tax rate is retrievable from the TaxService
///
public double CalculateTax(double fine)
{
// Get the tax rate using the appropriate service
double taxRate = GetTaxRate();
// calculate the fine
tax = taxRate * fine;return tax ;}
That way, I can remember where I was if I get interrupted, the comments aren't an afterthought, they are a part of the process and, if I get hit by the Programmer bus, someone else should be able to see what I was doing. Obv. the example is small and trivial, but that's how I work and I fail to understand the 'don't need comments' brigade. What I do hate is/...
// Multiply the rate by the amount
return rate * amount;which is simply a case of bad commenting in my book - it is not necessary to comment every step
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
CalculateTax()may be a bad name - it may not be specific enough. It's not that far away fromDoSomething(). OTOH, provided it's a private method, used in a context where its meaning is obvious, why would it still need comments, especially if its body reads likereturn amount * db.GetTaxRate()? Oh, you haveGetTaxRate()in the same class, and it's accessing the database directly? That's a clear case poor encapsulation, where two classes, one coupled to the persistence layer and one strongly rooted in the business logic are shoved into a single one, and which need to be separated. I too profoundly dislike comments. I think comments are a code stench (M. Fowler calls them smells, but I think "stench" is more descriptive). Every time I see comments in code I find that they are either useless (the code is quite understandable even without them) or are used to mask other problems (the code absolutely needs some refactoring). Properly maintaining comments anywhere except in libraries which you develop for use across several projects, which you may plan to distribute without source code, is IMO waste, in terms of agile methods, and should therefore be eliminated. Comments are also the source of many stupid problems. Since the compiler doesn't check comments, they tend to quickly become buggy, this being the case especially in heavily commented code. Having been bitten by this many times, I tend to disregard comments, and as such heavily commented code is annoying for me, since I have to skip large portions of prose to get to the parts which actually matter - and which I can actually trust. Also, if you read a C++ header file or a Java or C# class file, and there's maybe 10 lines of comments between any two method or member declarations, you might get a very good understanding of the individual members, but loose the overall understanding of the class you're looking at. This increases the chances of introducing changes which break the overall architectural consistency, or even rightout introduce subtle conceptional bugs which are hard to diagnose. Really, if your code needs commenting, take a better look at it, and think how you can refactor it into smaller, more specialized functions, with better names. Your code should become easier to read without comments if you do such refactorings. And there's a non-documentation-related gain too: you'll notice that code duplication goes down and your code becomes more compact. In his book "The art of Unix programm -
I see you have a very firm stance on your coding techniques and best practices, and I get the strong feeling that you do not appreciate the alternative. My original post was not intended to dissuade, but I really don't like some of the overly eager approaches being taken by certain 'shops' and where it is in turn expected that my 'shop' hold these same values. If I were to come into a situation where inlined comments allowed an automation process to produce clear documentation--and this was the best solution--I would post this as well. To date I have not! And again, not too sound as though this is standard across the board, but of all the code I've worked with the standards seemed pretty much the same. I'm kind of bothered how the first quote you made was abbreviated out of its original context. Not every 'shop'--as you put it--is an agile code tank, and that was my point.
Xittenn wrote:
Not every 'shop'--as you put it--is an agile code tank
Agree wholeheartedly! :) But note that automated generation of API documentation is unrelated to using agile development process. Not sure why you connected the two. The nice thing about using automated API documentation generation tools like JavaDoc[^] and Sandcastle[^] and NDoc[^] is that they allowa a single source of comments (i.e. in the code) to be maintained. This makes it easy to ensure that the generated docs are up-to-date and reduces the risk of introducing miscommunication between the author of the comments and another team that may be tasked with producing the documentation. I didn't mean to imply that end-user documentation (user's guides) can be created without the assistance of a technical writer. /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
-
Xittenn wrote:
Not every 'shop'--as you put it--is an agile code tank
Agree wholeheartedly! :) But note that automated generation of API documentation is unrelated to using agile development process. Not sure why you connected the two. The nice thing about using automated API documentation generation tools like JavaDoc[^] and Sandcastle[^] and NDoc[^] is that they allowa a single source of comments (i.e. in the code) to be maintained. This makes it easy to ensure that the generated docs are up-to-date and reduces the risk of introducing miscommunication between the author of the comments and another team that may be tasked with producing the documentation. I didn't mean to imply that end-user documentation (user's guides) can be created without the assistance of a technical writer. /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
I connected the two based on high correlation!
Ravi Bhavnani wrote:
The nice thing about using automated API documentation generation tools like JavaDoc[^] and Sandcastle[^] and NDoc[^] is that they allowa a single source of comments (i.e. in the code) to be maintained. This makes it easy to ensure that the generated docs are up-to-date and reduces the risk of introducing miscommunication between the author of the comments and another team that may be tasked with producing the documentation.
And if that's appropriate for your project by all means use it. I don't believe that the above holds as fact for all projects. Automation is not as simply implemented as you make it sound, and this is why a good number of teams do not implement such a strategy. For starters, in my 'shop' documents are created before code not the other way around. Versioning comments in combination with code becomes a chore when the code should be following the documentation. And back to my original statement, if all that is being commented and documented is the formatting of the code, the coder should be able to read the code on its own or else it isn't very well organized to begin with. My argument is not that there is never a circumstance where comments are not required. My argument is simply if you do not require them there is no obligation by some imaginary standard that others have created.
-
:thumbsup::thumbsup::thumbsup: Been there, done that, have tooo many t-shirts. I used to work with S/370 Assembler programmers who would tell me it was a waste of time to comment the code since the instruction tells you what it is doing. I made the same argument that it doesn't tell you why. If they weren't telling me not to comment, they were griping the S/370 had too many instructions. As far as they were concerned, you only needed Load, Store, Add, and Branch. I suppose years later they were in nirvana when RISC was announced. Of course they didn't like going through my code since I used (shudder) MACROS and (horrors) symbolic register assignments instead of hardcoded numbers. That last part really blew there minds because I'd have code that read
BALR RTN, PRINT
instead of
BALR 8, PRINT
Psychosis at 10 Film at 11 Those who do not remember the past, are doomed to repeat it. Those who do not remember the past, cannot build upon it.
My God. There are really programmers who think it's okay to write S/370 assembler without comments? I thought I'd read the whole Book of Engineering Sins, but I must have missed that page.
I can only offer one comparable instance of evil, though in this case it was an evil development tool: a microassembler for a highly unusual synchronous communications device. This lashup had five parallel processors on it: an ALU, a microsequencer, a memory access controller, and two bus bridges. Its 48-bit-wide instructions had to address all five at once, with...interesting constraints and side effects regarding timing and conditional operation.
I was handed this device, the documentation for it (which was sketchy), and the existing microprogram for it, and told to make a range of enhancements to it. Imagine my surprise when I opened up that microprogram -- approximately 4000 instructions long -- and discovered that it contained not one single comment.
Needless to say, I immediately looked up the previous maintainer, who was overjoyed that the responsibility had passed from him, and inquired about the lack of commentary. He then told me the most incredible thing I've ever been told about a development tool:
"The microassembler doesn't allow comments."
It was true. I hadn't had any idea before he said so.
I spent the next six weeks, over the strenuous objections of my management, writing a new microassembler for the damned thing. Three years later, when the responsibility for the device passed from me to a young successor, the program was fully commented.
(This message is programming you in ways you cannot detect. Be afraid.)