September 17, 2014 at 6:23 am
Gary Varga (9/17/2014)
Jack Corbett (1/5/2009)
...I worked for/with an excellent developer who did not document well...In my opinion, that is an oxymoron. Excellent developers document well. The definition for "document well" is up for debate though...even five years on 😉
I get your point, but my point is he wrote and likely still writes great code. It does what it needs to do and does it efficiently. The issue was, and probably still is, that he thought his code was self-documenting, but he was about 3 levels above me when it came to coding, so I needed documentation to understand the what and the why of what the code was doing.
Jack Corbett
Consultant - Straight Path Solutions
Check out these links on how to get faster and more accurate answers:
Forum Etiquette: How to post data/code on a forum to get the best help
Need an Answer? Actually, No ... You Need a Question
September 17, 2014 at 7:13 am
Jack Corbett (9/17/2014)
Gary Varga (9/17/2014)
Jack Corbett (1/5/2009)
...I worked for/with an excellent developer who did not document well...In my opinion, that is an oxymoron. Excellent developers document well. The definition for "document well" is up for debate though...even five years on 😉
I get your point, but my point is he wrote and likely still writes great code. It does what it needs to do and does it efficiently. The issue was, and probably still is, that he thought his code was self-documenting, but he was about 3 levels above me when it came to coding, so I needed documentation to understand the what and the why of what the code was doing.
Don't put yourself down Jack! The more 'above' you are the easier and clearer your code should be in my book. If a seasoned developer (which I assume you are) cannot follow the code, then it may well have succumbed to the vice of excessive cleverness.
Gaz, I'll agree with you on your list, and cannot see anything to change there.
September 17, 2014 at 7:21 am
I'm sure this'll invite some ire but I hate comments in code. I view the need to write a comment as a personal failure for which I should locked in the stocks and pelted with rotton fruit. Jeff Atwood wrote a really good blog article [/url]about this a few years back and reading it really changed the way I write my code.
It basically boils down to the fact that your code can be self documenting but it's hard to do, much harder than just writing a comment in fact. But once written it's easier to maintain. The real trick is not that you need pick apropriate function names but rather that you need to decompose to apropriate functions. They need to be small, really small, and do just one very succint thing. If you can achieve that then it's obvious what they do from the name and the tiny amount of code. It's also obvious what the calling procedure does because it reads like a script of steps.
I'll freely admit, I often fail in this regard. Time constraints often mean I don't have time to decompose the code as thoroughly as I'd like and then I'll put in some explanatory comments because I'm not a sadist and I don't wish my successors ill. I will try to revisit and decompose the code in less interesting times if I can though.
As for other types of documentation I only really see the need for two broad types: contractual/auditable (what has your customer signed up for and can you verify that your tests meet that contract) and operational (e.g. how do we bring our production server back up).
September 17, 2014 at 7:49 am
crussell-931424 (9/17/2014)
...also some of the comments here are so huge, bigger than the original article, that I didn't bother reading them. Sometimes less is more.
Yep 😉
Gaz
-- Stop your grinnin' and drop your linen...they're everywhere!!!
September 17, 2014 at 7:56 am
FunkyDexter (9/17/2014)
...Jeff Atwood wrote a really good blog article [/url]about this a few years back...
...and the example fails either due to the lack of a comment OR proper naming. The code does not contain the essential information that it is a Newton-Raphson approximation. This is EXACTLY the sort of information that should be in a comment as it describes the square root approximation used but would allow a change in the type of approximation used without adversely affecting the caller.
EDIT: Silly use of wrong word. Sorry.
Gaz
-- Stop your grinnin' and drop your linen...they're everywhere!!!
September 17, 2014 at 8:07 am
The code does not contain the essential information that it is a Newton-Raphson approximation.
Actually I agree with you there and I think it's the one flaw in the article. However the solution is not to add a comment. The solution would be to either:-
1. Rename the method to SquareRootWithNewtonRaphsonApproximation or if that's not possible (ie because it's already in use and you don't want to risk refactoring)
2. Create a new method named SquareRootWithNewtonRaphsonApproximation and have SquareRootApproximation call through to it.
That second option highlights a technique that I've found crucial in writing comment free code - single line functions. Often a single line of code can represent quite alot of functionality, particularly when you start using lambda functions, linq etc. There's nothing wrong with breaking that single line of code into it's own method with an explanatory name.
September 17, 2014 at 8:15 am
Fair comment FunkyDexter.
It would be interesting to see how realistically maintainable software is after a decade of changes.
I don't say this from a for or against viewpoint but solely as an interested observer. It would be great if this was objectively measured and monitored on a number of projects of varying size and complexity to see if this technique works in practice and when.
Gaz
-- Stop your grinnin' and drop your linen...they're everywhere!!!
September 17, 2014 at 8:50 am
It would be interesting to see how realistically maintainable software is after a decade of changes.
I only started making a concious effort to switch style 2 or 3 years ago so I'm not in a position to comment (come to think of it I kinda doubt that any of the code I write ten years ago is still in production but that's by the by).
I will say that my early attempts at comment free code were largely failures. I think there were two main reasons:-
1. I didn't decompose finely enough, or I got carried away and decomposed the wrong this. You don't really need a separate method to open a connection any more than you need a comment to tell you what conn.open() does:rolleyes:
2. While I may have been a good boy when I write the code I was often sloppy when I maintained it. E.g. I'd take a previously simple method and add complexity to it without spending the time to refactor properly. If you do this your nice succinct method name will go stale just as quick as a comment will.
As I've gone on using the technique I think I've become better at it and my gut feeling is that my code stays fresher for longer than it did was I was more comment happy. These days about the only comments I use are to describe why I've used an implementation that might seem counter-intuitive (i.e. because the intuitive way proved to be flawed and I want to save a subsequent developer the pain of having to find that out for themselves).
One criticism I would make of this aproach - it can lead to lots of small methods. That's fine if you've got a nice swanky ide that makes navigation nice and slick but if you're some kind of old school purist who thinks an ide is for the weak and that real men use notepad then it'd be an absolute nightmare. In can also be intimidating for a subsequent developer if they're used to large methods becasue they're often not used to using the navigation capabilities of their ide - but I think I'd argue that's a lesson they could do with learning.
September 17, 2014 at 9:16 am
FunkyDexter (9/17/2014)
...One criticism I would make of this aproach - it can lead to lots of small methods...
...and how does that work with TDD?
Gaz
-- Stop your grinnin' and drop your linen...they're everywhere!!!
September 17, 2014 at 10:01 am
Gary Varga (9/17/2014)
The following are a few principles that I try to follow:
Gaz - mind if I add one?
Document any updates, additions, or other modifications to the code with a full description, who did it, and when.
The reasoning should be obvious, but to some may not. Any introduction or addition of new logic by another person might change both the paradigm and the "cleverness" of the code. And sorry to say it, a new introduction to the code may be a kludge some by one who did not understand the masterpiece, like a band-aid on a Rembrandt.
Not all gray hairs are Dinosaurs!
September 17, 2014 at 10:15 am
...and how does that work with TDD?
TDD favours small methods so very well. If you're in the camp that says you should only write test against the required functionality it doesn't give you a huge benefit but if you're in the camp that writes tests for the implementation then it gives you much tighter control. Personally I fall somewhere between the two. Mostly I'm interested in the functionality but I'll also write tests for any parts of the implementation where I think it's crucial that it behaves in a certain way.
September 17, 2014 at 10:38 am
Miles Neale (9/17/2014)
Gary Varga (9/17/2014)
The following are a few principles that I try to follow:Gaz - mind if I add one?
Document any updates, additions, or other modifications to the code with a full description, who did it, and when.
The reasoning should be obvious, but to some may not. Any introduction or addition of new logic by another person might change both the paradigm and the "cleverness" of the code. And sorry to say it, a new introduction to the code may be a kludge some by one who did not understand the masterpiece, like a band-aid on a Rembrandt.
Don't mind at all 🙂 One could argue that it falls under "Everything needs documenting", however, I am a big fan of being explicit.
Gaz
-- Stop your grinnin' and drop your linen...they're everywhere!!!
September 17, 2014 at 11:38 am
I worked for several years in a one person shop. I still put comments in the code, ESPECIALLY little utility snippets. If I can't tell what the code was supposed to do six months later, how could anyone else?
[font="Verdana"]Please don't go. The drones need you. They look up to you.[/font]
Connect to me on LinkedIn
September 17, 2014 at 12:21 pm
I was drawn in by the first paragraph of the editorial:
"I was having lunch with a friend the other day and he talked about how much documentation he has to complete for a project and he was lamenting on how much he hates writing documentation. "
Most of the subsequent discussion focuses on a single (albeit major) element of documentation: documenting code and changes therein. But the statement above implied "project documentation". I felt as though the arguments they had may have been about two disparate things.
In reality, there are three major "documentation" areas to be addressed in any "project" based on the intended audience: 1) User documentation - how users are going to use the tool to get done what can be done. 2) Administrative documentation - how administrators manage the behind-the-scenes elements of the project to keep the system healthy (eg. managing user access rights, reference table updates and extensions, etc.). 3) IT documentation - how the code accomplishes the target deliverables for users and administrators. It isn't just keeping code documentation coherent that is important. It is synchronizing the changes across all these areas that is needed ... and difficult.
Documenting inline code is just one element of the 3rd area (system integration, module integrity, etc. are others). I wrote extensively on this in the 70's trying to develop standards to guide my project teams through the maze. I have overseen hundreds of projects from NASA manned mission support to hospital lab data management to bid management systems. What always fascinates me is how often people use the term "documentation" and are completely neglectful of the varieties of documentation needed in support of any project of use in a business.
I once wrote code for a lab start-startup that I was recently hired as a consultant to retire... just 6 months ago. Who can know the changes that enter code over that kind of lifetime - 26 years? How many times did they add "functionality" to the user interface requiring updates to the User documentation? How important do inline comments become over "generations" of programmers? What systems now interact with (or even DEPEND on) the code and underlying tables?
It is essential to recognize the NEED for documentation for EACH audience and to know that whatever level of documentation you decide on for IT (code commenting, external flow diagrams, etc.) it needs to lead the current worker quickly to the changes that are needed in that environment for the problem at hand.
September 17, 2014 at 12:35 pm
Thomas Abraham (9/17/2014)
I worked for several years in a one person shop. I still put comments in the code, ESPECIALLY little utility snippets. If I can't tell what the code was supposed to do six months later, how could anyone else?
Just as important (for documentation even if you are the only one who will need to rad that documentation) is the CYA policy (cover your arse) wher when someone asks you X months or years later why a certain change was made you will have the notes in your documentation.
I have been documenting changes for ciustom reporting for years and I havce personally seen notes I made over 5 years ago pay off when I;m asked to reviww something to determine where a specifc change had occurred and why it changed as well as who requested the change. I will even make 'Developers Thoughts' and comments in my notes that describe what I was thinking at the time in case (at some later point) I need to understand why I choose the path I did for implimenting some change.
I can't stress enough how much my own documentation has paid off later on.
Kindest Regards,
Just say No to Facebook!Viewing 15 posts - 76 through 89 (of 89 total)
You must be logged in to reply to this topic. Login to reply