|
Colin Davies wrote:
So what's the point in internal understandability or comments ?
When the initial developer of an application is fired/leaves and the client has to get a new developer to maintain the application.
We recently had this exact problem. A client was in trouble as a contractor had developed a system for them and then buggered off to London. They needed some new features and so sent us the code. It was very hard to read code. Technically it worked well, the architecture was sound and the system at run-time worked. Took us ages though to work through the non-understandable code without comments.
Colin Davies wrote:
This proves that the code initially accepted was not up to scratch.
I disagree. No system can be programmed at the outset to meet all future requirements. Businesses change and require new features in existing applications. Rewriting the app is insane, the business may only have changed slightly.
Colin Davies wrote:
Adding comments and attempting to make code understandable to third parties, just proves that you have no confidence in the future of your code.
Another facet is this; We work on many projects at once and trying to keep how each one works code wise in my head at once is impossible.
At times I will be phoned on a saturday night and asked to "quickly" fix something on a 6 month old project that has long entered the Recycly bin of my mind. Having readable code with comment-pointers is invaluable at 1am on a Sunday morning. 
Paul Watson
Bluegrass
Cape Town, South Africa
Crikey! ain't life grand?
|
|
|
|
|
Paul Watson wrote:
Businesses change and require new features in existing applications. Rewriting the app is insane, the business may only have changed slightly.
No the spec and requiremnets have changed. This is no longer maintenance, but enhancement.
By now altering the original working code, you are actually as an analogy, placing an old modified part in a near new car.
This is neither good or fair for the client in the long run.
Quite likely this act of "maintenance" will introduce *bugs* into a good product.
Paul Watson wrote:
We work on many projects at once and trying to keep how each one works code wise in my head at once is impossible.
This is a real concern and a problem created by managemment, having a developer working on multiple projects simultaneously can only degrade performance.
Its like having all the car pieces in a garage as the workers work on cars thrown into one pile.
This is in effect what the management are doing with you.
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch ![Green Alien | [Alien]](https://www.codeproject.com/script/Forums/Images/alien.gif) "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
Colin Davies wrote:
Its like having all the car pieces in a garage as the workers work on cars thrown into one pile.
Don't be so dramatic Colin, you sound like me.
Obviously I don't sit with three IDEs open trying to code three projects at once. What I mean is a developer is not going to spend a solid month on one project alone. In a perfect world this would be the case, but even I don't live in that world.
Anyway, you are trolling :P
Paul Watson
Bluegrass
Cape Town, South Africa
Crikey! ain't life grand?
|
|
|
|
|
Paul Watson wrote:
Anyway, you are trolling
Yes, I confess.
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
How arrogant are you?
So you've never had to go back and change an application to meet new requirements? Suggests to me that was because it was never really used.
When an application is dependable and reliable it becomes part of a companies life and essential to operations and as business requirements change, the software needs to as well.
Re-usablility is crud! I have libraries that I regually drop into new application and can build a new CRM or PIM application for a company in about a week. WHY? because my crud is designed properly and works well 
|
|
|
|
|
LeeDaviesVBSource wrote:
How arrogant are you?
Very.
LeeDaviesVBSource wrote:
So you've never had to go back and change an application to meet new requirements?
Yes, I use to go back and make modifications etc.
But I have now learned that if my development was well organized initially it easier to just rewite segments or classes in their entirety. Maybe this as easier for me then other developers, as I seem to recall all the breakthrough stuff that was needed to be done the first time, and subsequent versions are just a matter of keyboard skills.
LeeDaviesVBSource wrote:
Suggests to me that was because it was never really used.
The royalty payments I recieve suggest businesses are still paying for stuff from a while ago. Unsure if they use it though. 
LeeDaviesVBSource wrote:
Re-usablility is crud!
I think you are misquoting me out of context here.
LeeDaviesVBSource wrote:
WHY? because my crud is designed properly and works well
Good.
So what's the point in commenting it !
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch ![Green Alien | [Alien]](https://codeproject.global.ssl.fastly.net/script/Forums/Images/alien.gif) "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
OK, Ok. So you don't believe in commenting. What about your documentation or don't you believe in that either?
I personally use .Net's XML documentation feature. Explain what the proc is supposed to do and return and if there is a problem with the function the new developer can just re-write it.
How about that for a compromise?
(P.S. You've started a good one here  )
|
|
|
|
|
LeeDaviesVBSource wrote:
What about your documentation or don't you believe in that either?
I believe in documentation !!
Ok first you should have the original requirements handy, sure you can add them with /* */ to the source code if you wish so they don't get lost, but visual requiremnets need to be on paper.
Also you should document what ever has been imported or used externally in the project||application. And of course if it's a team, who did what.
How the application or whatever was tested and what paramaters were used. (this is really useful)
Last of all how the Application and classes or libraries or whatever are to be used, so that you can have reusability of what is is good.
Since originally posting I have altered my mind as to commenting, and now consider that there are a lot of exceptions.
Understandable code is different as its got a lot to with ability and perception.
I have heard of professional developers that don't get *pointers*. Ok they manage to survive, but I'm sure when they find code that really uses pointers etc, they are befuddled.
I keep meaning to move to .NET, so until then I can't comment.
LeeDaviesVBSource wrote:
How about that for a compromise?
Cheers
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
Colin Davies wrote:
If a solution is required, it doesn't matter if it is created in C++. C# VB, Pascal, Forth, Lisp, or Lego. What matters is if it meets the requirements of the client. Commenting and creating understandable code is a micro issue.
I respectfully disagree. I think it *may* depend on your range of experience, environment, level of co-workers (co-workers are often like your family: you can't choose them)
My experience says otherwise. I worked in a shop where we spent several years getting out from under several things:
Bad code design
Slapdash technique
Difficult to understand and maintain code.
There were times, (I sh*t you not) where what could have been done in 10 to 15 lines of code, had been done in 40 pages of code-- no comments.
No, difficult to understand code by itself is not often THE issue, but it can be a major factor. If I am doing a debug of a program, I don't step through every line of code. My employer couldn't afford it. I need to look at blocks of code, get the gist of what's going on, and eventually I'll zero in on the pertinent sections. Broad comments can help eliminate entire sections/functions very quickly.
If you've been lucky/fortunate to work in an office with highly compitent co-workers (or you work in a one man shop) readability and understandability are going to drop sharply on the list of 'must haves' because you're not speaking to a very wide audience.
Where I think your complaint can be legitimate, is corporations which get bitten by the beaurocracy bug want to institute some kind of hard line structure comments which end up taking as much time to puzzle out as the original code does. I can't agree more that this often becomes a process in and of itself thus causing you to add time to the top of the process that you cut from the bottom.
Comments or understandable code don't have to become a chore. IN the case of comments, a simple sentence can help eliminate a section of code.
//Get patient master record from database, parse.
And if the programmer is looking for the part of the code which prints the patient statement, he knows he doesn't have to puzzle out what's going on here, he can move on.
Is there a perfect system? Hell no. But I can tell you from experience, that our development time dramatically reduced once we added just a few INFORMAL practices. Again, we didn't move to some kind of god awful AT&T Bell Labs style UML IEEE documentation system. Just a few informal rules of thumb, and you can eliminate a lot of tripwires and traps in the future.
Paul
|
|
|
|
|
Paul Oss wrote:
Broad comments can help eliminate entire sections/functions very quickly.
Agreed !! with an additional emphasis on Broad.
Paul Oss wrote:
But I can tell you from experience, that our development time dramatically reduced once we added just a few INFORMAL practices.
I use to quite heavily comment stuff, and "refactor" code to be more understandable by peers.
To be honest I often find comments harder to understand then the actual code, and this includes my own comments.
Seriously I think when you are actually coding the perspsctive of what a later reviewer will understnd of the comments is influenced by your own mind state at the time. Thus maybe the best person to comment code is not the actual developer.
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
Colin Davies wrote:
To be honest I often find comments harder to understand then the actual code, and this includes my own comments.
Seriously I think when you are actually coding the perspsctive of what a later reviewer will understnd of the comments is influenced by your own mind state at the time.
No doubt that this can be the case. But that still goes back to the perfect world scenario. If you can't understand the comments, then you're back to square one and having to interpret the code- nothing lost. I don't think that I've ever lost anything significant by difficult to read comments, other than the fact that I will admit that the annoyance factor is high. I may not be losing time, but it makes my blood boil when I spend 4 hours going through nearly unreadable code only to find the comments annoyingly vague. I remember one of my favorite comments that was often made by a particular programmer... a comment I never really deciphered was (in an old version of a business basic (mainframe stuff)):
REM DO VAL SH*T
To this day, I never figured it out.
The only place where time can be lost by comments is when they're logically wrong. But in my experience this has been relatively rare.
Some of you may disagree with the technique, but when I suspected that a one line comment would leave more questions unanswered than answered, I would simply write a whole paragraph describing my reason for doing what I did, what the weaknesses were, where future problems could arise, and how future programmers might deal with changes-- and sometimes my thoughts and feelings on the subject at large. And honestly, they were the most useful later on. Because yes, Colin, I do have to admit, there have been times-- albeit rare-- that I didn't know what my own comments meant.
Paul
|
|
|
|
|
Instead of //Get patient master record from database, parse., how about:
<br />
PATIENT_RECORD * pPatientRec = getPatientRecord();<br />
parsePatientRecord(pPatientRec);<br />
- Renault
|
|
|
|
|
So... what you're saying is make code easy to read. See previous remarks.
|
|
|
|
|
Wow. You're serious.
Your attitude is part of the reason most software sucks.
Colin Davies wrote:
If they can't understand it without comments, then that's actually good, because you don't wan't some 3rd rate hack messing with your masterpiece.
Most maintenance programmers _are_ third rate hacks. That is to say, maintenance programming is usually the first assigment programmers get when they start a job. So you think it's OK to make the code impenetrable so that maintenance programmers can't work on it?
|
|
|
|
|
Jim A. Johnson wrote:
So you think it's OK to make the code impenetrable so that maintenance programmers can't work on it?
Actually, I think its a darn good idea. The Maintenace programmers are likely to make modifications that will cause new problems and a whole new cycle of maintenance will need to be paid for by the client.
Mediocre programmers touching valuable code and being led by comments sounds dangerous to me.
Without comments these programmers will need to both learn what is going on and how it occurs if they want to make changes. Alternatively they can write a replacemmet class or procedure.
The real problem is that at both development and maintenance the management are likely to push for early completion resulting in substandard work.
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
Colin Davies wrote:
Actually, I think its a darn good idea. The Maintenace programmers are likely to make modifications that will cause new problems and a whole new cycle of maintenance will need to be paid for by the client.
Cloin. You're approaching utopian arguments. This is like the people who say a safety on a firearm is completely unnecessary because if you have a safe handler, the firearm will never accidentally go off. You're right. But that's in the year 2976 when we all walk around in white linen clothes, put our hands together, bow and say 'greetings brother' when we cross paths on the street. But until then, the world aint perfect, therefore we institute things called 'building codes', 'traffic lights', 'road signs', 'blade guards and well commented readable code.
Paul
|
|
|
|
|
/*
Write a good documentation, with all features like procedure header, function description,... . See, you don't need any comment in your code. And if the other don't understand your code-he's just not good enough for working with your code.
*/
Comments are only useful in one language-vbasic. Basiccode have to look like this.
Sub Form_Load()
'Dim a as Variant
'Dim b as Variant
'Init a, b
End Sub
//VB-looks much better with comments.
//Excuse my bad English 
|
|
|
|
|
What a bunch of crap, Colin!
Most engineering has some type of blueprint. All the programmer might get is the bit of comments left by the fella before him.
Not every programmer is an expert in the language they are coding in. whether it's the one creating the mess or maintaining it. Coments are the only way to help give the next guy a clue as to what you were aiming at.
"Manifest plainness, embrace simplicity,
reduce selfishness, have few desires."
-- Lao Tzu BW
|
|
|
|
|
brianwelsch wrote:
Most engineering has some type of blueprint.
Yes, but the blueprints are for the designer or the project creation team to develop. The programmer is working to there specification, he/she should not be developing the project.
Have you ever seen a Maintenance programmer ask to look at the original user requirements or specification?
brianwelsch wrote:
Coments are the only way to help give the next guy a clue as to what you were aiming at.
What about logic and ability, and dataflow analysis and deskchecking, have we left those skills in the dask ages ?
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
Colin Davies wrote:
What about logic and ability, and dataflow analysis and deskchecking, have we left those skills in the dask ages ?
In the past 18 mths. I've coded a c++ project from scratch with very few specs. It was being redesigned halfway through, because of some new ideas from the powers that be. Also, it was my first C++ project beyond classroom code. So the code I added through helped me quickly figure out what I was thinking and what was going on.
Currently, I'm dabbling in assembly, another new language for me, which isn't even standard, but littered with macro calls. I'm grateful for the couple of comments which are given.
I do alot of plotting out by hand, following data through by hand, etc, but the clocks ticking.
"Manifest plainness, embrace simplicity,
reduce selfishness, have few desires."
-- Lao Tzu BW
|
|
|
|
|
(ducks grenades being lobbed by Davies)
Software Zen: delete this;
|
|
|
|
|
Gary Wheeler wrote:
(ducks grenades being lobbed by Davies)
Nah, I wouldn't do that.
I didn't really expect anyone to agree with me though.
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
When I'm in a 'let natural selection take its course' sort of mood with regards to my co-workers, I agree with you. Fortunately for them, that only happens a couple times a week  .
If you take a look at my post[^] below, you'll see how I choose what to comment. If it is more consise to say something in code, I'll do so. If it's more straightforward to say it in a comment, and let the const's fall where they may, I'll do that.
Software Zen: delete this;
|
|
|
|
|
Maybe I have been turned away from comments and understandability in recent years by the ammount of over commented understandable code that is poorly written.
I think if some programmers put as much effort into programming well as what they do to commenting then we would be all a lot better off.
Yes, there are places for comments, in the start of files, and in headers for access, etc.
But commenting every line of code like:
iLoop++;
has become far to prevalent.
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
Indeed. Once I started commenting only what I needed to, my productivity went up. It's embarrassing how much time I used to spend, documenting every little thing:
int i;
Nowadays, I use comments to explain rationale, insert references to background material, and describe version history.
Software Zen: delete this;
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
