When I was coming up as a young VBA pup I was told again and again “all good programmers document their code,” and “constant documentation a good developer makes” and “blah, blah, blah document” and I hated it. I hated documenting, I hated figuring out something fun and then going back and explaining it to someone else in English. I always associated documenting code with reporting and testing as the vegetables of programming, I didn't like it but it was essential for success. The reason it was important, I was told, was because if another programmer had to work with your code you wanted them to know what they are looking at. You wanted them to be able to get right to work and not have to spend much time gearing up and learning the system. I believed this for much of my 27 years on this earth, but lately I have realized one thing, if your programmer needs documentation in order to be able to quickly pick up on what it is doing one of two things are true: either the programmer sucks or, more likely, your code sucks.
Now, I'm not talking:
//This method was created because the full select query was costing performance, so we made this one to call back only two values.
That type of commenting is important because sometimes you need to quickly remember why you DIDN'T do some things in ways that you usually would. We don't always research our bug trackers and dev logs before fixing something we perceive to be broken or done incorrectly. This way we don't change something that we did for a reason we may not remember.
I'm more speaking of:
//07/06/08 S. Chipps This method retrieves a dataset from the DB that contains the records that were entered between the two dates passed. First the values are tested to make sure the second is greater than the first then we insert them into the query to get the data we are looking for.
An oversimplified version of what I am talking about, but you get the drift.
Alright, so, there is no reason anymore to record who wrote the method (or function for you naked C folks), we have source control now. It's much more accurate when you are looking to throw some blame around, so sociopathic coders can't frame others for their crappy code. So, basically, writing manual for your code basically says that there is the chance the person reading it may not understand what they are looking at. There is no good reason for this, besides the fact that they are new to the field or technology. However, in that case, I think the best thing to do is allow them to figure it out for themselves or sit with them and explain it.
If you've been fortunate enough to witness a truly beautiful application, learning what a piece of it does is not a chore. Everything is exactly where it should be, the variables? Extremely self explanitory. The data? Corresponds with the variables. The objects? Exactly the same as the data. The methods? You can read the name of them and pretty much learn exactly what they do, if you're still curious look down... everything is done in the simplest, leanest, cleanest way possible.
What's my point? Stop documenting code, stop asking your coders to document, stop thinking that documentation is a staple in programming. Because it's not, everyone else has realized it. You shouldn't need to document how to install your application, how to set up your local environment, or what third party executables to run in what order before compiling the second time. If you find that is not the case then you're doing it wrong, and your time would be better spent fixing it rather than writing about it.
THE END
Don't forget the coders that are still learning!!! I'm not a pro-programmer. I do it for fun and while yes, I suck tremendously, I absolutely love the challenge of getting the code just right (especially when its on the first try!).
ReplyDeleteDocumentation is necessary for those that might not be as capable as you. I'm a math major, and sometimes I come to a really simple problem where the obvious escapes me (don't act like we all haven't been there before), and some kind of explanation is necessary.
We're not all like you. Documentation opens the ability to interpretation to everybody. There is no point in whining and complaining about documentation. Or else programming languages, math, and most thesis papers would cease to exist. :-
great point! but when you are doing calculations at work or in class do you put notes by each step so whomever reads it understands what you did? No, if you write them correctly and cleanly the people that should know what it does will and for those who don't there are books for that, or they can go to school to learn it. Right?
ReplyDelete;)
Another one of these blog posts bashing code commenting...
ReplyDeleteNot every user of your code can see the internals of it (i.e. may only be able to see the method signiture, not the implementation). This is most nessicary when your code is becoming part of a library that doesnt have source attached.
Comments also help when you find it nessicary something new when something else exists with the name you would of liked to of used.
Besides, when your working on large projects, most of the time you cant remember why you even wrote a certain method or class, and that is when you go looking at the comments for hints.
Steve Yegge had a rant about commenting a while back.
ReplyDeletesteve-yegge.blogspot.com/.../portrait-of-n00
I'm with Steve on this one. I don't really comment my stuff that much anymore, and I spend more time removing stuff of the /* increment variable foo */ foo++ stating-the-blindingly-obvious variety.
Having said that, there are times where commenting / documentation is absolutely essential. It's to do with the why. Why has the code been written this way? What hidden agenda can't you see from the code, no matter how closely you look at it?
Supposing you're doing something a bit wacky to work around a bug in a third party API. You want to comment _that_, otherwise the next person to take over the project might take one look at your code, think which dweeb wrote this, and reintroduce the bug without even realising it.
Or, a good example of when you may actively want to document something in your install is You have to reregister frobnicate.dll because the latest service pack for Vista 64 bit ultimate broke our installer three days ago and we haven't bribed the developers enough pizza yet to fix it.
Good documentation, like good testing, is hard for most developers. It comes with practice. You almost need to imagine yourself in another developer's shoes and thinking if I had just the code to read, what would I make bad assumptions about and get tripped up on?
But you do still need it.
Richie,
ReplyDeleteI think we perfectly agree. Great article, thanks.
Commenting code is an a href=http://devjargon.com/development/the-art-of-commenting-code/ art form/a. Too much and it useless, too little and people start wondering why you're doing things.
ReplyDeleteYou're totally write. Tell who wrote what code is useless, it just makes your program look sloppy, adds useless lines and is pointless. But smart documentation and commenting is necessary.
If you have created an API, documentation is absolutely necessary for the users of that API. If you've created a standalone app that no one is ever going to see the code, documentation is probably useless.
While there's certainly a problem with over-documenting, I find the javadoc-style documentation very handy (even though sometimes I find myself putting the incredibly dull comments about what some methods do in there).
ReplyDeleteComments within the method itself tend to irritate and confuse me more than anything else, especially if they are multi-liners (short and sweet ones are sometimes acceptable).
Anyways good read, found it through DZone thanks for posting.
Yeah documentation sux
ReplyDeleteEither way, thanks for doing an awesome job on my hair last night!
You are not only an awesome Developer, but also a master Beautician!
xoxo
I agree with the post but also with Alex but from a C#/.NET point of view. I have used JavaDoc, PHPDoc and now the XML Comments in C# with Sandcastle but that is the limit to the documentation I put into my code unless there really is an important reason to add a comment.
ReplyDeleteI don't feel I need to explain in laborious detail *what* my method does or *how* it does it, the method name, parameters and return value should be the clue.
I find the insert-language-hereDoc style comments work for me and those who then use my code to write their own assemblies, the organised API documents that many of the tools produce can be invaluable, just like MSDN can be at times (or at least in my opinion).
Good post though
Standard Pragmatic Programmer (paraphrased) - Comment why you did something, not how you did something.
ReplyDeleteI've always applied the following rule-of-thumb to comments or docs: They should be minimal, but sufficient.
ReplyDeleteMinimal may be any small amount down to and including 0.
I think the first paragraph of this post sums it up for you and a good many of your counterparts. You don't like documenting.
ReplyDeleteOver and over again I hear this pure bulls**t that comments are a sign of bad code. All I can say is good luck when you come back to your own code in a few years and realise that you wish you had commented it because you don't remember why you did things.
The good news for me is that I don't employ you.
Generally you should comment the INTENT, not the IMPLEMENTATION. The code is the WHAT, but only you know the WHY and if you don't spell it out those who follow after you (or yourself if you're revisiting the code later) can't evaluate the degree to which the code accomplishes its purpose.
ReplyDeleteImplementation comments _are_ useful around compact / concise logic that is doing a few things at once -- it can save a reader from having to delve deeper into the rabbit hole to understand whats going on. And also if you are doing something unusual you should comment your reason(s) as well. You might have come up with a brilliant and elegant solution, but if you don't provide the CONTEXT for what lead you to the solution and why its better than more commonly used approaches its just an oddity to someone else.
Commenting is more difficult than coding.
ReplyDeleteIt is not easy to imagine who will read your comments.
Whereas you know well the compiler and its needs :)
in any case I agree that documentation like javadoc, e.g. this method takes an id as String, bla, bla, bla is not useful at all, neither to write nor to read.
Comments allow other developers to learn. No matter how 'beautiful' you believe that your code is, someone else will see it as $hit. That is the nature of being a developer; we all have our own way of writing code. I comment for other developers that will come after me and to provide a clear explanation for others that may not understand what I wrote.
ReplyDeleteYour views are very elitist and I agree with DocumentMan wholeheartedly that I'm glad you don't work for or with me.
I completely disagree. Documentation is as necessary as coding itself. I wonder how many years of experience you have in programming and what has been the scope of your project in terms of duration and number of peoples involved.
ReplyDeleteDocumenting code in the code file itself is very essential for several reasons. It allows your fellow peeps to easily follow your flow without delving deep in the API to identify what your logic is. Not always function names could be descriptive enough to detail the inherent logic applied. Also, the description and comments show up in the intellisense which tells you what the API is intended for and what the individual parameters mean and their types.
I agree that oversimplification of the algorithm is not required but standard comments (like function info and param descriptions etc) must be provided, and if required some code description could be provided as simplification of a complex piece of your creativity!
Comment, just don't comment the crap out of it. I agree for the most part say WHY not what.
ReplyDeleteThat being said, a little bit of what is okay if you're say, the only person in a given shop working with a language. Say you're doing a rails app, but you live in a shop of .Net guys. (Poor suckers...), somehow you've managed to get Rails in the door (you friggin miracle worker) and now there are some critical things being done in that app.
Training is coming up for other devs to get on board, but that night, you win the damn lottery, get killed, get offered a job paying millions, or receive a marriage proposal with attached W2 that satisfies you and you don't return.
Now someone has to figure out something that is nearly foreign to them.
I liken it to speaking spanish without an interpretor. Sure you may recognize a few words here and there, but do you actually understand what you are hearing??
Anyway, I partially agree...say why not what. That being said, I also agree with the person who mentioned documenting your methods and such if you are producing a library but not attaching source code.
I'll shut up now.
I use GhostDoc to comment methods and properties of a class, just for the use of documentation generation with sandcastle. This is pretty handy and adds vs intellisence documentation. I only use the // comments if there is a need for it. // TODO:, // REVIEW:, etc. to tell why something is working but not 100% perfect, because there was a deadline and solving x was just costing too much time. Or when I don't yet know what the best solution is now, but want to move on and look back later at it. If I forget to look back at x, than at least that knowledge doesn't get lost when moving from programmer to programmer or if I look back at it 1 year from now. Luckely VS allows you to add // TODO: and // REVIEW: comments to a TODO list :-)
ReplyDeleteI've seen a lot of code where commenting is used to create a sort of inline methods. A block of logic, that does something. It's a way better practice to extract this to a method, so the logic is reusable and the name of the methods is mostly equal to the comment line.
Another bad one is comment code above a method call inside another method, mostly containing a description of the method, this is very bad practice if you refactor a lot, since comments won't get refactored :-( The following situations can appear in your code than:
// Get's a glass of milk for user
GetMilkAndCookiesForUser(username);
The comments are outdated now and don't add any value at all.
Still it is questionable if the amount of comments is dependanble on the knowledge of the team. If there is a large group of just starting coders it might be better to have more comments in your code. Might be a more productive team, but this might keep the level of the team down.
I wish I could learn to program without books, tutorials, guides, sample code, or seminars. I mean, they're all just forms of documentation. We don't need 'em!
ReplyDeleteOh, and I think this is a great example of self-documenting code, don't you?
$/='!';$_=e.;s/./qw!${ -- }while$ 0 ++$ ($$a=ord+getc)-10|| --$ print+chr$ ++![(ord$)%13%9].'$a;'/eg;eval
Or, you know, maybe you'll actually think things through next time, realize that nothing is black and white, and there are plenty of good reasons to provide intelligent, sparse commenting/documentation for any code you write.
My take has always been that if you are forced to comment your code, you probably could rewrite or refactor to make things a bit more readable. Comments should be a last resort, IMHO.
ReplyDeleteThanks,
James
Exactly what Abhishek said.
ReplyDeleteRubbish.
ReplyDeleteIt's obvious what your code does by reading it only to other coders of your level or higher. What about the junior coders in your shop? What about your documentation builders (e.g. Javadoc) ?
I used to feel the same about unit testing, simply because I hated doing it. As with unit testing I've seen the benefits of commenting code and now attempt to evolve and improve my commenting along with my code.
Comments don't go with code - they are part of the code.
I agree with many others. Comments are not meant to explain what or how, but why. When working on multi developer projects, especially ones where standard practices may change due to client specifications, comments are helpful for those who follow in your foot steps. Why did he do that, oh I see. Why is there a strange snippet of code in the middle of this otherwise standard method... oh, see comment. And, in response to this post, I am posting this comment. ba dum bum.
ReplyDeleteComments and documentation are a neccessary part of code. They exist for the benefit of both yourself and everyone else. We've all stepped away from code for a few weeks and had to figure out what we were doing again. This was the point where we should have learned to make comments in our code.
ReplyDeleteFurthermore, not everyone thinks in the same way. Not everyone who thinks differently or can't figure out your code is an idiot. You are not the center of the universe.
Why would you even have regular comments that long to begin with? Learn to use XML comments for your methods and types.
Plus, if you use descriptive method, type, and field names, most code is self documenting. If your code is written properly, the only comments needed are small bits in complex pieces of code, not 50-line monster chunks slapped in the middle of code.
The bottom line is that it's not all about you. Get over yourself. Install Sandcastle and Docproject, and run them after you do a final build. It takes ten minutes.
Oh, and while I appreciate that it's cool to mock old-school programmers who know ASM, C, and C++, I have to wonder if you could write a bubble sort routine from scratch or handle pointers.
There's something to be said about languages that force you to create things like constructors and kicks your teeth in if you don't instead of decreasing the collective intelligence of its consumers by introducing things like object initializers and automatic properties.
Microsoft -- always catering to the lowest common denominator, and fanboys like you follow along like lemmings the whole way.
no one has ever called me a fanboy, lol. That's great.
ReplyDeletefangirl?
I wasn't making fun of C developers! C++ is the first language I learned.
I think people are really missing the part where I said:
Now, I'm not talking:
//This method was created because the full select query was costing performance, so we made this one to call back only two values.
That type of commenting is important because sometimes you need to quickly remember why you DIDN'T do some things in ways that you usually would. We don't always research our bug trackers and dev logs before fixing something we perceive to be broken or done incorrectly. This way we don't change something that we did for a reason we may not remember.
I do agree that if the why is different than your usual why you should comment it.
I appreciate all your responses... (even the ones that don't agree)
You're missing the point. The point of comments is less to help you and more to help other people.
ReplyDeleteIt doesn't take too long to put comments in if your code is written properly and you create documentation using XML comments (or whatever the analogous functionality is in whatever language you are using).
The point is that your statement Documentation == Garbage Code is overly broad. *Excessive* documentation can == garbage code, or at least code that needs to be refactored to be less complicated.
Self-documenting code, combined with reasonable commenting is a basic courtesy to other developers.
I see your point, we agree to disagree.
ReplyDeletePS I am the Jesus of Development, and with my infallible wisdom I have forgiven you, my son. Go forth and sin no more.
Yes, my name here may be stupid, but at least I don't run a blog where potential future employers post and tell me they're glad I don't work with or for them.
ReplyDeleteI'm not trying to pick a fight with you, my development brother. Don't take yourself so seriously.
ReplyDeleteI'm sure to my future employers my work will speak for itself. I hope I'm never in the position that I have to change my development ideologies to take a job. However, if I do, and my employer wants very well documented code I will, of course, give them that.
I'm not unreasonable, I just have an opinion.
Documentation, like anything else in this life, used in large quantity, is BAD !!!
ReplyDeleteI think you don't need to document any line of code. And if you really need to do this somewhere in your code: Be quick or be dead.
My comments is always in the method summary (ooo Visual Studio, such nice IDE :) ). Explain the master idea of that method, the parameters. Thats it.
Documentation is a good idea to other people know what that method do/or returns.
See ya !
A very experienced and accomplished programmer (Guillermo Rozas, author of the MIT Scheme compiler) once made roughly the same argument to me: if you can't read the code itself, then it's lousy code. And comments that are out of date are actively misleading; only the code can be trusted to be accurate.
ReplyDeleteI suppose I should have been persuaded, but I wasn't. For data structures, especially, it's valuable to explain the conditions that all the code will carefully maintain; it's a waste of time to expect programmers to read all the code and figure out not only what it does, but what it carefully avoids doing.
In large programs, it seems to me that one needs to be able to use a module or package without knowing the details of how it works. You don't have time to read all the code. How can one do this if the interfaces aren't explained?
I'm sure to my future employers my work will speak for itself. I hope I'm never in the position that I have to change my development ideologies to take a job. However, if I do, and my employer wants very well documented code I will, of course, give them that.
ReplyDeleteI'm not unreasonable, I just have an opinion.
Well a couple comments there would be that writing code isn�t an ideology its work. It can be creative and it can be fun but it�s not the same as say being a doctor and refusing to do something that will hurt someone. I wouldn�t worry so much about going against some hidden coding �morals�
Also it�s not that you are being unreasonable, it�s just that you are not seeing the overwhelming evidence provided by your peers showing that you may be wrong.
Documentation is a necessity. It�s not even that big a deal to do if you are prepared for it. I think it�s funny that there are any strong opinions on a subject so trivial.
I really wish you were able to see that when your work matches your ideology it is no longer work.
ReplyDeleteIf I chose to believe everything that people that considered themselves my peers believed, I would not be close to the person I am today.
Thank you for reading.
The rules i've set for my team are as follows:
ReplyDelete- Write code in as obvious as fashion as possible. Variables and function names that make sense, simple solutions to complex problems. See Occam's razor
- If you're doing something exceptional or something against the grain, THEN document it
Some people here really take things way too seriously. The warnings of potential stunted future employment...wow, that is awesome! Seriously, that one really gets the eyes rolling. Thanks for keeping it fun. A person who is too uptight to entertain a contrary position to one's own isn't someone I'd want to work for, with, or within 100 feet of.
ReplyDeleteOkay, that out of the way, I definitely agree with most here that there has to be some middle ground. I can't stand missing XML comments. However, I see that as an exception since it affects the usage of a class object outside of viewing the actual class code itself. I also don't even have a problem with comments about the how if the situation warrants it. Just be judicious with comments.
Generally speaking, when I have to sift through line after line of mostly useless comments so that I can figure out what some convoluted 900 line method is trying to do, I'm already annoyed that I have to work that developer's code in the first place.
I've been working on a conversion project where there are none of the original developers left in the building anymore. They commented everything...who, what, when, where and why. There are even comments about the departmental manager that requested the change and half those guys don't even work there anymore. That being my situation, I find myself somewhat sympathetic to the article at this point in time.
Ooh, a flamewar *dives in*.
ReplyDeleteHere's the thing though: in my opinion, documentation is good. Comments on the other hand, may be good *or* bad. Comments can quickly become something that's definitely not documentation.
When the WHY of something is not obvious, it should be explained in a comment.
When the HOW of something is unclear, the code should preferably be clarified. IF that's not possible, or there is no time or some other constraint prevents it, it should be explained in a comment.
Public APIs should be documented with the appropriate documentation comment facility.
It should not be necessary to document the WHAT. If the class and method names are so unclear that you need to do it, you've got other problems. But as always, there are exceptions to this rule. :)
Somehow (correct me if I'm wrong), I got the impression this matches what schipps was trying to say. Whether or not others agree remains to be seen. :)
More recent discussion on the same topic:
ReplyDeletewww.codeodor.com/.../2293
What if you monkey patch something in say ruby? Should you not document that you have changed the string.+() operator to attempt to add the two strings together rather than concatinating them like would be expected?
ReplyDeleteI'm going to disagree. I just got added to a late project (depending on who you listen to, it is 3 or 4 years late) where the only comments are code that is commented out. The specs are meaningless, there is no design doc on how the app works - because it is a port to .net of a vb3 app and the vb3 app is the reference model.
ReplyDeleteAll the comments in the code are things I've added as I've made my tiny little pieces work. They're as much notes to myself as to the next guy why did Peter do it this way? Because some of the code is crap that the offshore team wrote. And some of the code is new stuff and some is, well, I just don't know. The other real developer on the project (the 3rd person is the team lead who bollixed up the offshore stuff) is so busy and heads-down that he's grumpier than I am and he's half my age.
@Peter - You bring up a great point. IF YOU ARE A CRAPPY DEVELOPER DOCUMENT YOUR CODE.
ReplyDeleteUnfortunately, most people don't know if they suck, so the rule should be document.
My opinion is, if your code is perfect, it needs no documentation. SO maybe instead of not documenting, people should be trying to make code that needs no documenting.
Does that make sense?
@Rytmis - THANK YOU
@SeanJA - if something is done in a way that is not normal it should be documented. PS The ebay XKCD is my favorite. Freaking cry everytime I read it.
I prefer reading books in eNglish than in C#/Java because I understand it better. If a comment saves me a minute when i look at it, it would probably save me 1 hr by the end of the day. When you have lambda's in your code it does not always reflect clean code but hey it saves me time to write a comment than re-doing something without lambdas.
ReplyDeleteI agree with Sara. I've seen many bad commenting standards and practices that only produce unnecessary clutter that becomes a maintenance nightmare. The actual code is the ultimate truth of how a program works. Comments need to change when the code it describes is changed. This isn't too difficult or time consuming with sparse, terse, and useful comments, but it quickly becomes an issue when the number of comment lines is close to or even greater than the number of lines of code.
ReplyDeleteI work on software where some other developers get pissed when you don't put a standard comment block before every function. Alot of developers still follow this practice, and it's downright retarded. I'm talking useless crap like the name of the function in the comment along with listing every single parameter along with a required comment for each parameter. Then there's a description section, and a returns section and a section where descriptions of bug fixes go along with a date, bug id, and who made the fix (none of which is typically relevant information, and it is all kept track of automatically in the source code version control system).
I end up rarely reading the comments in this program to try to figure out what anything does because half of the comments are outdated, uninformative, and wrong. Plus who wants to take the time to read through all that junk. It's usually easier to figure out what a function does by just looking at the code.
I've seen it taken to the following extreme and there are people who will actually defend this nonsense.
// Author: John Smith
// Date Created: 1/1/2008
// Function Name: ButtonCancel_Click
// Pameters:
// Object sender - the sender of button click event
// EventArgs e - the event arguments object
// Description: This function handles the button click event for the Cancel button
// Returns: nothing
// Changes: none
void ButtonCancel_Click(object sender, EventArgs e)
{
Close(); // closes the form
}
Just as bad is having to write detailed documents describing what some code does. The argument is usually something like just in case you get run over by a bus, how can we ever figure out what the software you wrote does.
Why are writing these documents usually a bad idea? First of all, they are outside the code, so if the code changes significantly then you have to remember where the document is and to keep it up to date. Which also takes extra time. Also, although there are exceptions, many software developers are horrible writers. Let's face it, many software developers can't write decent understandable English, and that includes the ones that were born in America.
Development tools have gotten to the point it is not that difficult to look at code and figure out what it does, especially well written code that has small amounts of useful comments and good names.
In a previous company, one software developer was notorious for not commenting.
One day we decided to look at everyones code and figure out on average how many lines of comments developers had per 100 lines of code.
At this company most developers averaged about 10-20 comment lines per 100 lines of code, while he was at about 1 per thousand.
To this day I still think the 10-20 number is good. Comments at the start of a function should be limited to a short description. There is no need for excessive comment blocks at the top of every source code file, or for every class, struct, enum, interface, etc. And please, do not comment every single variable declared in a function.
There are some good reasons for commenting more than this. for example if you are writing an API used by the outside world and you need to add JavaDoc/XML doc comments to your code that will go into help documentation for your users.
But other than exceptions like this, short and sweet should be the rule.
I generally err on the side of document this if it's going to confuse ME when I come back and look at it later.
ReplyDeleteGood code employs intuitive variable and method names, so if it's done well, most documentation is not needed. There are cases however, when I absolutely do NOT want somebody coming along and reworking something I struggled with for days and I'll often comment the (insane)logic I used to reach that approach, or I've even been known to be a smart ass with a comment such as:
//Do not touch this or flying monkeys will come out of your keyboard and bite you on the nose. See Dana first.
I'm with you Sara. I hate redundant commenting. If the code is well formatted, it will state what it does fairly clearly.
Having personally gone through the extremes of no comments (early programming days) to comment nazi (a few years back) I have come to my own personal conclusion that some comments can be a good thing but that inane comments or worse still, comments that are out of sync with code, are evil.
ReplyDeleteOut of curiousity I looked through a project I just completed. It has just over 600 lines of C# code (after cleaning up with ReSharper) and 17 lines of comments. That's just under 3 lines of comments per 100 lines of code. Not that ratios mean a damn thing. Some classes have no comments at all because they're self documenting from my point of view.
This is code for an HttpModule that interacts with a database, lives in the GAC, but is configurable by each app on the server. Definitely not something that's light and fluffy. But by naming methods and variables appropriately and adding just enough comments to describe some of the more complex logic points it's something that anyone on my team could look at a year from now and figure out what's going on without too much trouble.
There is a separate documentn on how developers use this module with their application. That's a must. It's ridiculous to send developers looking at code that's designed to behave as if it were a 3rd party component. But that's describing the outer surface only; like the owners manual for your car.
A method with a signature like public void AddEntryToDb(Entry entry); is pretty self explanitory in what it's doing. A line of code like $/='!';$_=e.;s/./qw!${ -- }while$ 0 ++$ ($$a=ord+getc)-10|| --$ print+chr$ ++![(ord$)%13%9].'$a;'/eg;eval is going to confuse anyone. It would be very helpful to have a comment describing what it does and WHY it was done in this terse manner instead of a more verbose one that's easier for mere mortals to read. (disclaimer: the cryptic line of code was written by Kenneth in his post on 7/9/2008 and I have no idea what it does or why it would be done that way).
I guess I'm agreeing that commenting is an art form. In most cases less is more, but don't under do it any more than you should over do it. If you find yourself writing comments that are just restating the method name then stop and ask yourself if you really need that comment.
Quite frankly, this has got to be the stupidest piece of advice to developers I have ever heard.
ReplyDeleteThe problem is not the code, or the varying skill sets of coders who follows in your footsteps, it's the person doing the documenting.
Often, this is the coder. And if you're having a problem with doing it or doing it well, then your approach is wrong. Documentation bookends actual development, with a plan, intent, and then after the fact, with notes and diagrams about implementation.
Therefore, the only thing you need to put IN the code itself, is notes about the strange cases where when you write something that might be a little foreign or out of context, when not accompanied by the bookends.
Development = labor, DOCUMENTATION = sustainable profitability
Thank you for your sharing!
ReplyDeleteAgree with your point of view
ReplyDelete