Are long procedure names bad?

[Trond]

I like to use descriptive names, and I now started to wonder if this was getting out of hand. Obviously I try to keep them as short as possible, but it's always more important to accurately describe what the procedure actually does.

Here's some of the names:
ExpressionApplyPrecedence()
SubtractLoadedFloatFromLoadedFloat()
SwapPrimarySecondaryRegister()
TokenizedExpressionToPatternedExpression()
CompareLoadedIntWithLoadedIntCommon()

I was happy with these names because they easily tell me what the functions does.

But just now, I found myself unable to create a well-describing name that was short enough (even within the above limits)! So the question is, when to sacrifice accuracy for a shorter name?

[Kale]

So the question is, when to sacrifice accuracy for a shorter name?

Never! Always make your procedure names as descriptive as possible. It helps your head in the long run.

[va!n]

names as descriptive as possible and as small as possible...

use GetWndSize() instead GetWindowSize() if possible and as long as its clear what the function is for...

Even some API commands are a lot smaller as the PB versions ^^

[Kale]

names as descriptive as possible and as small as possible...

Why?

[Dare]

names as descriptive as possible and as small as possible...

Why?

So we're not forever scrolling sideways ..


I agree with va!n - short as poss within descriptive enough to make sense.

Descriptive helps with understanding and readability but long lines that exit stage right don't help.

IMHO.

[va!n]

@Kale:
Dare said it

commands like CompareLoadedIntWithLoadedIntCommon() are looking like absoltly nightmares to me. ^^

[Kale]

@Kale:
Dare said it

commands like CompareLoadedIntWithLoadedIntCommon() are looking like absoltly nightmares to me. ^^

Maybe, but you would kiss yourself when working on that self explanitory code in 6-12 months time.

[PB]

I don't see why long names are necessarily bad. One could argue they're
longer to type, but with the editor's AutoComplete it's not a valid argument.
I agree with Kale: just make them descriptive enough to know what they do.

If anything, longer names probably add the risk of typos if you don't use the
AutoComplete feature, and they certainly make your source files larger, but
I don't feel these are a reason to avoid descriptive names.

[Dare]

@Kale:
Dare said it

commands like CompareLoadedIntWithLoadedIntCommon() are looking like absoltly nightmares to me. ^^

Maybe, but you would kiss yourself when working on that self explanitory code in 6-12 months time.

There is nothing wrong with meaningful names, in fact it is important. But you can have meaningful names without actually writing a manuscript.

Code: Select all

Procedure ThisCodeSubtractsTheSecondParameterFromTheFirstParameterInTheArgumentListAndReturnsTheResult(firstParameterAsLong.l, secondParameterAsLong.l) ; The procedure has two arguments, both are signed long (4 byte) integers. Purebasic will object if you try to call this procedure without EXACTLY two parameters. 
  ProcedureReturn firstParameterAsLong - secondParameterAsLong
EndProcedure

Example of overKill and pointless comments.

[Trond]

On the other hand, if you named that piece of code "Sub", does it subtract (if so, what? integers? floats? strings?) or does it parse a subroutine?

[Baldrick]

Nothing to stop you shortening obnoxiously long names & putting a comment in your code comments somewhere for reference in 6 months time

Code: Select all

;- procedure explanations for myself in 6 months time
; ThisMinusThat(A.l,B.l) really means: "ThisCodeSubtractsTheSecondParameterFromTheFirstParameterInTheArgumentListAndReturnsTheResult(firstParameterAsLong.l, secondParameterAsLong.l)"
; WhatWhen(A$,B$,C.l,D.f) really means: " blah blah ......."

Procedure ThisMinusThat(A.l, B.l) ; The procedure has two arguments, both are signed long (4 byte) integers. Purebasic will object if you try to call this procedure without EXACTLY two parameters. 
  ProcedureReturn A - B 
EndProcedure

Debug ThisMinusThat(10, 8)

[Trond]

But if I have 32 different procedures which subtracts A from B in different ways, I can't call them all SubtractThisFromThat().

[Kale]

But if I have 32 different procedures which subtracts A from B in different ways, I can't call them all SubtractThisFromThat().

Then you should code one routine that works with flags.

[Dare]

But if I have 32 different procedures which subtracts A from B in different ways, I can't call them all SubtractThisFromThat().

You could call them SubtractThisFromThat1 through SubtractThisFromThat32 or Mary, Jane, Bob, Rover.

BTW, what do you think of hyphens in proc names?

Code: Select all

Procedure TakeBfromA_normal(a.l, b.l)        ; Bog normal subtraction, dunno why I proc'ed it!
Procedure TakeBfromA_abnormal(a.l, b.l)      ; Kinky way to subtract B from A
Procedure TakeBfromA_clever(a.l, b.l)        ; My clever way to subtract B from A
Procedure TakeBfromA_fast(a.l, b.l)          ; fast way to subtract B from A
Procedure TakeBfromA_slow(a.l, b.l)          ; slow way to subtract B from A
Procedure TakeBfromA_bloated(a.l, b.l)       ; Pretent we're MS
Procedure TakeBfromA_trim(a.l, b.l)          ; Slower than slow but so tight I gasp with pleasure!
Procedure StealBfromA(a.l, b.l)              ; Banker's way to subtract B from A
Procedure TakeBfromA_yetta(a.l, b.l)         ; Another way to subtract B from A

And if something needs huge commentary, what about referring to an external doc:

Code: Select all

Procedure WhatIsThis(AndWhyDoICare.q)        ; See techdoc chapter 8, section "WTF IS THIS"

[Trond]

You could call them SubtractThisFromThat1 through SubtractThisFromThat32 or Mary, Jane, Bob, Rover.

The problem is, that then it won't be very readable. Of course by the procedures themselves I can write comments, but everywhere I use them? And every time I want the procedure I need to lookup its name!

Compare:

Code: Select all

SubtractIntFromLoadedInt(Pos.l)

SubtractLoadedIntFromLoadedInt()

SubtractConstantFromLoadedInt(Pos.l)

SubtractFloatFromLoadedFloat(Pos.l)

SubtractLoadedFloatFromLoadedInt()

SubtractFloatFromLoadedInt(Pos.l)

SubtractLoadedFloatFromLoadedInt()

SubtractLoadedFloatFromInt(Pos.l)

SubtractConstantFromLoadedFloat(Pos)

SubtractLoadedFloatFromFloat(Pos.l)

SubtractLoadedFloatFromConstant(Pos.l)

SubtractIntFromLoadedFloat(Pos.l)

SubtractLoadedIntFromLoadedFloat()

SubtractLoadedFloatFromLoadedFloat()

Code: Select all

SubtractAFromB0(Pos.l)
SubtractAFromB1(Pos.l)
SubtractAFromB2(Pos.l)
SubtractAFromB3(Pos.l)
SubtractAFromB4(Pos.l)
SubtractAFromB5(Pos.l)
SubtractAFromB6(Pos.l)
SubtractAFromB7(Pos.l)
SubtractAFromB8(Pos.l)
SubtractAFromB9(Pos.l)
SubtractAFromB10(Pos.l)
SubtractAFromB11(Pos.l)
SubtractAFromB12(Pos.l)
SubtractAFromB13(Pos.l)
SubtractAFromB14(Pos.l)

BTW, what do you think of hyphens in proc names?

Dreadful!