Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.programming > #1496 > unrolled thread

bigger and worse?

Back to article view | Back to comp.programming

Contents

  bigger and worse? bob <bob@coolfone.comze.com> - 2012-04-24 07:17 -0700
    Re: bigger and worse? Mark Storkamp <mstorkamp@yahoo.com> - 2012-04-24 09:39 -0500
      Re: bigger and worse? Daniel Pitts <newsgroup.nospam@virtualinfinity.net> - 2012-04-26 11:19 -0700

#1496 — bigger and worse?

I remember the days when we had functions with short reasonable names like printf, scanf, and fopen.

Now, they seem to have names like dequeueReusableAnnotationViewWithIdentifier.

Shouldn't there be some effort made to keep functions and identifiers short and easy to memorize?  

[toc] | [next] | [standalone]

#1497

In article 
<20993941.1062.1335277059630.JavaMail.geo-discussion-forums@ynlp3>,
 bob <bob@coolfone.comze.com> wrote:

> I remember the days when we had functions with short reasonable names like 
> printf, scanf, and fopen.
> 
> Now, they seem to have names like 
> dequeueReusableAnnotationViewWithIdentifier.
> 
> Shouldn't there be some effort made to keep functions and identifiers short 
> and easy to memorize?  

Decades back when I used Brief as my editor, I had set a bunch of 
abbreviations for frequently used awkward function names that would 
automatically expand when entered. My current editor won't do that. I'd 
rather have the longer self-documenting names and decent tools to deal 
with them than to have a bunch of short cryptic names.

[toc] | [prev] | [next] | [standalone]

#1500

On 4/24/12 7:39 AM, Mark Storkamp wrote:
> In article
> <20993941.1062.1335277059630.JavaMail.geo-discussion-forums@ynlp3>,
>   bob<bob@coolfone.comze.com>  wrote:
>
>> I remember the days when we had functions with short reasonable names like
>> printf, scanf, and fopen.
>>
>> Now, they seem to have names like
>> dequeueReusableAnnotationViewWithIdentifier.
>>
>> Shouldn't there be some effort made to keep functions and identifiers short
>> and easy to memorize?
>
> Decades back when I used Brief as my editor, I had set a bunch of
> abbreviations for frequently used awkward function names that would
> automatically expand when entered. My current editor won't do that. I'd
> rather have the longer self-documenting names and decent tools to deal
> with them than to have a bunch of short cryptic names.

+1

Short names are fine for *extremely* standard symbols. Anything else 
should be as descriptive as is /useful/. That particular name seems 
likely to be too specific, but without knowing the problem domain I 
can't really tell you.

<opinion type='personal'>
Usually a method/function/routine has several types of "documentation", 
including the name. The different types have different purposes:

Names should tell you "what" the routine does. fetchCurrentUser, 
connectToDatabase, etc... They shouldn't tell you how, why, or when to 
call them.

Function documentation (such as JavaDoc, etc...) should tell you "why" 
to call this routine, and the pre/post conditions.

Internal documentation (inline comments, etc...) should explain "how" 
the routine attempts to do what it does, if that isn't clear from the 
code itself. The comments should *not* be "call foo", since I can read 
the code, I know foo() is calling foo.  The comment instead should be 
"Use foo to calculate final result of x", if that isn't clear.

Which algorithms are used should be documented as well. Sometimes it 
makes sense to put them in the Function Documentation area, if that is 
part of the contract of this routine.  Other times it makes sense only 
internally. A justification of "we chose this algorithm because..." (it 
was easy to implement, it was fast enough, it works, etc...), is often a 
good thing to include.

Again, if something is "dead obvious", don't comment about it.  This is 
a subjective decision, keep in mind who is going to read this, and when. 
  3 years from now, will you remember why?

All of these are "rules-of-thumb". As always, if following these causes 
problems, then adjust for the situation.
</opinion>

Anyway, I know that went further than discussing method names, but the 
point is that they are an important part of documentation.

[toc] | [prev] | [standalone]

Back to top | Article view | comp.programming

csiph-web