I tried to reply via groups.google.com with imbedded responses but the formatting is so messed up that I gave up.
Suffice to say that I have no argument with you on the validity of some comments - and in particular those that describe the "why". In actual fact, the vast majority of comments in the many hundreds of programs I've seen over the years describe the "what" - like, the following code does X Y & Z - and the code that follows is often not as good as it would have to be to stand up on its own. It's like the comments are being used as a crutch. The comments seem to have given licence for the developer to go ahead and write thoughtless, shabby code. It's more difficult to write clear, well-structured code, using well-chosen variable names, so as to make description superfluous. It's also right, in my opinion, to assume that the programmers that will be working on the code in time to come will be... um... not necessarily as adept as to take "G += (A++)+(-l--)" in their stride, for example. With that little bit more thought and effort in the first place life can be so much more pleasant - and uncluttered - for those that follow. Looking for common ground... if you've seen the main common block in some well-known, very large software products, they're sometimes choc- a-bloc full of cryptic variable names - like one- and two- character variable names. Their very existance dictates that there must be comments and/or associated documentation to describe the "what" - or every techie is going to have to go to a hell of a lot of effort to trace where each of those variables is initialised, populated and/or used before he/she has the first clue what they're for... and there is sometimes a hell of a lot of them and a hell of a lot of code that uses them. It's a problem that is not easy to solve - although not impossible - and so the problem perpetuates and grows. That, I *do* believe, is an example of somewhat shabby work that results in comments being necessary. Mike. On Mar 4, 9:31 pm, Jim Idle <[email protected]> wrote: > Mike Preece wrote:On Mar 4, 6:10 pm, Simon > Verona<[email protected]>wrote:Agreed about the long term benefits of > rewriting! Also whilst we're at it - fire any programmer that uses goto, > return to, undescriptive variable names or seems incapable of writing > comments. Though I did work with a programmer who claimed comments were > unnecessary because the code was"self-documenting"!! Strangely enough he > also was a big "goto" user.... SimonPerhaps controversially,You mean > incorrectly.I believe that comments are often a result of somewhat shabby > work.This could not be more incorrect. The only way you could contrive to > make this correct is if the variable were all called A1 A2 A3 etc and they > have to be explained. Variables should be: > recordCounter > customerFile > and so on. Comments are rarely about explaining what the code does. I know > what COUNT() does and I can even infer G += (A++)+(-l--) does. Comments are > about WHY it does it, and no amount of jiggering about with the code explains > things like why are particular algorithm was chosen and so on. We would NEVER > have to think twice about these things. And anyway, it's only BASIC, it isn't > rocket science (expcet for the blokes at JPL that use jBASE that is).We ought > to think twice. Look at the code you've written and see if there are changes > you could make to it that would make it self explanatory.I was going to give > lots of examples and so on but I don't think there is any point. I think that > you must not have ever seen properly documented code. The comments rarely > explain the lines of code that are going to run. Comments say things like: > * Do not be tempted to change this algorithm basing it at 0 as then XYZ is > * required.... > * The front desk bell captain must be pinged before the bell as the > * front stufle pump will explode if this happens out of order more than > * 6 times - doing this here before starting the grunk engine guarantees order > * > * We must use a topological sort here as a straight qsort does not account > * for interdependencies and we must detect dependency cycles here > * > * Use dynamic arrays here because....That little bit of extra effort is, in > my opinion, better than taking the easy way out by throwing in a comment or > two.I am sorry but this is utter rubbish. How is adding comments taking an > easy way out - I think that perhaps you experience of other programmers can > have been only of relatively mediocre ones. Can I guess that a lot of your > code does not have comments in then, and you have self justified this by > saying "Ah, now I have formatted it a bit, it is obvious"? This isn't how it > works at all. Comments remind you of the thought process you went through 3 > years ago to type in the program. If I need comments for something I wrote 3 > years ago, then how can I expect someone who has never seen the code to get > the gestalt? > Also, do not forget that sometimes code that is harder to read might be > necessary because it is 10X faster and so on.One argument in favour of this > approach is that comments can end up misleading or extraneous after a code > change.It is part of your job as a programmer to look after the code. If you > don't update the comments, then you are not doing your job. The number of > times I have heard this crap from programmers is unreal. It is like your > mechanic saying "I didn't put in any oil in your car because it will be out > of date in 6,000 miles anyway". Just because there are comments does not mean > you don't read the code.It'd be easy for a programmer to get in and fix or > change something, get the code working as it should, and overlook that the > comment should also have been changed.Then he isn't really any good. Good > programmers are not hacks who do things that are 'clever' - programming is a > profession.And - to add some extra heat to this discussion - GO can sometimes > (although very rarely) have its place.Exit to error condition that does not > return. That's it. > Jim --~--~---------~--~----~------------~-------~--~----~ Please read the posting guidelines at: http://groups.google.com/group/jBASE/web/Posting%20Guidelines IMPORTANT: Type T24: at the start of the subject line for questions specific to Globus/T24 To post, send email to [email protected] To unsubscribe, send email to [email protected] For more options, visit this group at http://groups.google.com/group/jBASE?hl=en -~----------~----~----~----~------~----~------~--~---
