Re: Which do you prefer?

' Say good by to the apostrophe

// because it's forward slash's for you all soon.

The Grand Master
VB 6.0 Jihad - Fight for your history and future


RobinS wrote:
Well, it does depend on the code. As I said, and Cor agreed
with, adding comments that repeat the code is redundant. I
just add them to explain why I chose a particular method --
maybe because of something else that's happening somewhere
in the (huge) application, or because of a business reason.
Or if the code is really complicated, I'll put something in
to give the general idea.

I have known a lot of programmers that don't believe in it, but
my guess is they've never written anything so complicated it
requires a 30-page document just to explain the calculations
(been there, wrote the document), or they *have*, but they've
never had to change it or maintain it. *Or* they don't mind
spending days going through every line of code trying to figure
out exactly what it does. Ugh.

I even worked for one person who went through and *removed* my
comments. They said it made it harder for them to read the code.
About a year later, they called up and asked if I had a copy of
the code w/the comments in it (I did), and could I help them
figure something out because they had to change something in the
business logic, and they didn't have enough time to figure it
out by going through the code.

I guess the bottom line is that I tend to be detail-oriented,
and think about the long-term, and a few comments in the code
seems to make sense to me. I also have an appalling habit of
writing documentation for the really complicated stuff (like
the aforementioned calculations) to leave behind me. That's
just me.

Other people can make their own choices.

And that's *my* two cents'.

Robin S.
---------------------------------------------

"Tom Leylan" <gee@xxxxxxxxxxxxxxxxxx> wrote in message
news:O9%23AFVuGHHA.1216@xxxxxxxxxxxxxxxxxxxxxxx
Robin:

How can we hope to have reasonable conversations when people are arguing
against comments. I don't know where they work but I've seen millions of
lines of code and I'm sure each programmer thought the code was completely
clear when in fact it was plainly not. What seems obvious as it is being
written won't be so obvious 3 years later when 8 of the original
programmers have quit. But let's say I include a SSort() routine, would
developers recognize it as a "stable sort" just by reading the code? I'll
guess that 90% of the VB programmers haven't heard of a stable sort so how
can they recognize one? I'll also guess "what a dork doesn't he know
there is a sort method" is what some of the folks here would say.

But that is only one use of comments. They have been elevated in status
through the use of things like JavaDoc (in Java). In large apps I've seen
3, 4 and 5 versions of "identical functionality" simply because none of
the programmers knew the other functions existed when they wrote their own
local version. An automated system for producing printed documentation
would go a long way to reducing this stuff.

We also use them to track changes. With business critical apps (and I
mean daily or weekly turnaround schedules) it is important to know what
changed, who changed it, when it was changed and why it was changed.
There is no more sensible place to put this information than next to the
code that actually changed. And if you made a undocumented modification
and the $14 million a year client dropped the company because your change
ruined their system you can bet there would be repercussions.

They aren't fun, and the system isn't perfect but how on Earth can anybody
be arguing against commenting? I suspect it's a game... the "your code is
inferior because you have to comment it" gambit. But my code isn't
inferior it is as good or better and it has reasonable and useful comments
as well.

These types of threads come about continually, it's part of the coming of
age of software developers. I've had programmers (who "knew" they were
the greatest) tell me that programmers don't read documentation. When I
challenged that statement he asked if I thought the majority of
programmers read the docs and I answered, "no not the majority, just the
good ones."

Well that's my 2 cents... everybody carry on :-)



"RobinS" <RobinS@xxxxxxxxxxxxxxx> wrote in message
news:Bo2dndYoUMupXerYnZ2dnUVZ_tqdnZ2d@xxxxxxxxxxxxxx
It *does* help if he has more than average knowledge, but I
don't like to assume that whoever comes along behind me *does*.
Plus, why should the poor guy have to spend extra time figuring
it out, when I can just put in a comment for him?

Also, frequently it's a business-rule kind of thing, that's
not documented anywhere for the programmer. While I *love*
to get written business requirements from my clients, I rarely do.

The specs for the last application I wrote were in the form
of a bunch of fields written on a piece of paper torn out of
a spiral notebook with the instructions "These are in three
different applications that we use, can you please figure out
how to get only *our* data out of those applications, for
only these fields, and put them in a central repository for us?"

I like to leave external documentation behind with my finished
applications (in this case, I documented the database/table/fieldname,
and in most cases, the query used), but that's not always possible.

To each their own, I just like to leave a helping hand to
whoever comes along behind me. It only takes me a few seconds.
(I type 100+ wpm).

Robin S.
---------------------------------


"Cor Ligthert [MVP]" <notmyfirstname@xxxxxxxxx> wrote in message
news:uGlJsecGHHA.2456@xxxxxxxxxxxxxxxxxxxxxxx
Robin,

Your particular comment suggest that the one who read it is able to
understand what you are saying.

In this case he needs some more than average knowledge of code to
understand why something is done. That one does not need your comment,
he/she sees it and thinks, whow I would not have done it that way,
however according the quality of the rest of the program the developer
should have had a special reason for that. Let me think twice and than
probably sees the why.

For a beginner this kind of comments has no sense even with the comment
they don't understand it.

However again just my personal opinion.

In my opinion a good comment can be:
'See document xyz for an explanation of mathematics in the used code

Cor

"RobinS" <RobinS@xxxxxxxxxxxxxxx> schreef in bericht
news:tMqdnZ0zb7T3MerYnZ2dnUVZ_tudnZ2d@xxxxxxxxxxxxxx
I understand what you're saying. I'm not talking about comments
like this:

'define a variable to hold the count
Dim count as Integer

I'm talking about comments like this, that explain something out of
the ordinary, or explain *why* something is done a particular way:

'routine X seems like the logical place to put this instead
' of here in routine Y, but if you put it there instead of
' here, the dire consequences will be this
' (insert dire consequences). So even though this
' seems counterintuitive, don't move it. You'll regret it.
(seemingly oddly-placed code)

Robin S.
---------------------
"Cor Ligthert [MVP]" <notmyfirstname@xxxxxxxxx> wrote in message
news:O5D4L0bGHHA.4688@xxxxxxxxxxxxxxxxxxxxxxx
Tim and Robin,

Do you know what is the trouble with me.

I can always better read code than even my own in any language written
comments.

Beside me I have seen that most developers are not given with rich
possibilities to write comments (and to tell something you can
disagree with me; I have seen that those who are able to write very
nice comments often make very bad code).

Just my thought,

:-)

Cor

"RobinS" <RobinS@xxxxxxxxxxxxxxx> schreef in bericht
news:SYudnYThpPA_AOrYnZ2dnUVZ_q2pnZ2d@xxxxxxxxxxxxxx
I don't agree. I've written some really complicated programs
with complex statistical calculations, and I always put
in comments, if not for the poor guy who comes after me, then
for me 6 months later when I'm no longer working on it, and I
have to go back and fix it. It's been 2 years since I left
that software behind, and I still get e-mails thanking me for
documenting my code so well.

Robin S.
----------------------------------
"Master Programmer" <master_programmer@xxxxxxxxxx> wrote in message
news:1165455921.990418.179290@xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
No code should EVER need one single comment if it is written
properly.
It should be easy to follow without ANY explanation needed. If your
code needs comments to describe it then I suggest you go back to
school.

The Grand Master


Michael C wrote:
"Master Programmer" <master_programmer@xxxxxxxxxx> wrote in message
news:1165272758.241742.269670@xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Good programming is about leaving breadcrumbs for the next
person. Not
trying to show off by writting code that is not immediatly
obvious. If
it needs any comments to describe it - then you are a useless
programmer.

Hardly. I'd say if it needs comments to describe it and those
comments are
missing then you're a sloppy programmer.

Michael














.

Relevant Pages

  • Re: Which do you prefer?
    ... How can we hope to have a reasonable conversation when people are arguing ... Robin has stated it in my idea very well although not in one thread. ... guess that 90% of the VB programmers haven't heard of a stable sort so how ... An automated system for producing printed documentation ...
    (microsoft.public.dotnet.languages.vb)
  • Re: Your opinion on the Agner fog manuals.
    ... Thats exactly the reason for exposing it. ... why gives him the right to teach "advanced assembly programmers"? ... full applications in assembly language. ... Feel free to write the comparable documentation that preaches whole ...
    (alt.lang.asm)
  • Re: Which do you prefer?
    ... or because of a business reason. ... programmers have quit. ... developers recognize it as a "stable sort" just by reading the code? ... An automated system for producing printed documentation ...
    (microsoft.public.dotnet.languages.vb)
  • Re: Library Design, the script kiddies nightmare.
    ... But if they follow only the interface and documentation ... programmers as per its own web site and experienced programmers do not ... If only the masm32 library had been written by experienced programmers, ...
    (alt.lang.asm)
  • Re: Perldocs for Schwartzian transforms?
    ... to me that everything that you might ever want to reference should be ... included in the standard Perl documentation. ... programmers put in their comments? ...
    (comp.lang.perl.misc)
Loading