Page 1 of 2
Are long procedure names bad?
Posted: Sat Dec 02, 2006 2:27 pm
by 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?
Posted: Sat Dec 02, 2006 4:06 pm
by 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.
Posted: Sat Dec 02, 2006 4:27 pm
by 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 ^^
Posted: Sat Dec 02, 2006 7:03 pm
by Kale
va!n wrote:names as descriptive as possible and as small as possible...
Why?
Posted: Sat Dec 02, 2006 10:29 pm
by Dare
Kale wrote:va!n wrote: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.
Posted: Sat Dec 02, 2006 10:50 pm
by va!n
@Kale:
Dare said it
commands like CompareLoadedIntWithLoadedIntCommon() are looking like absoltly nightmares to me. ^^
Posted: Sun Dec 03, 2006 12:15 am
by Kale
va!n wrote:@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.
Re: Are long procedure names bad?
Posted: Sun Dec 03, 2006 12:56 am
by 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.
Posted: Sun Dec 03, 2006 4:49 am
by Dare
Kale wrote:va!n wrote:@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.
Posted: Sun Dec 03, 2006 12:13 pm
by 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?
Posted: Sun Dec 03, 2006 12:42 pm
by 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)
Posted: Sun Dec 03, 2006 1:21 pm
by Trond
But if I have 32 different procedures which subtracts A from B in different ways, I can't call them all SubtractThisFromThat().
Posted: Sun Dec 03, 2006 2:04 pm
by Kale
Trond wrote: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.
Posted: Sun Dec 03, 2006 9:47 pm
by Dare
Trond wrote: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"
Posted: Sun Dec 03, 2006 10:00 pm
by 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!