Programming Question
-
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.)
-
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.)
Fran Porretto wrote:
I spent the next six weeks, over the strenuous objections of my management, writing a new microassembler for the damned thing.
:thumbsup::thumbsup::thumbsup:
Fran Porretto wrote:
There are really programmers who think it's okay to write S/370 assembler without comments?
Yeah, unfortunately true. I left there after a year. The company declared bankruptcy the next day. I assume they decided without me there was no point in continuing. :laugh: But I got such delight in seeing their incredulous looks as they tried to decipher their own programs after a year. While my programs were profusely commented, I might not have bothered, they had difficulty following what I was doing. One of my first programs was to do database maintenance (back when databases were flat files). Until I came there, the "largest" program was a deck about 2-1/2" to 3-1/2" thick. I ended up carting 1-1/2 cartons (~3000 lines of code) around. They thought I was trying to write a compiler. I figured I was going to be stuck doing more database maintenance (they tended to put people in silos) and by making a macro generated generic program that I'd just have to declare a few parameters and be able to gen a new system for any other database that came my way in no time. It was able to handle multiple commands (Edit, Modify, Change, all mean the same thing) because I wanted people to be able to use it without having to read the operation manual (or as I titled it, "Care and Feeding"). As you can tell, 37 years later and I still proud of it.
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.
-
So you aren't using source control? :((
In some instances source control isn't available, but even where it is used, I still write my comments in the code... Call me old fashioned.
Silence is golden... but duct tape is silver!! Booger Mobile - My bright green 1964 Ford Falcon - check out the blog here!! | If you feel generous - make a donation to Camp Quality!!
-
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')
_Maxxx_ wrote:
// calculate the fine tax = taxRate * fine;
... and THAT is -5 vote Remember: NO comment is NOT AS WORSE as a WRONG comment ! You don't calculate the fine but the tax.
-
_Maxxx_ wrote:
// calculate the fine tax = taxRate * fine;
... and THAT is -5 vote Remember: NO comment is NOT AS WORSE as a WRONG comment ! You don't calculate the fine but the tax.
Yeah, well, in my defence I was making it up as I went along! ;)
MVVM# - See how I did MVVM my way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')