3 ms·
> Code must always be "self documenting" This is in practice very hard to achieve. One reason is that a fully self-documenting name of a functiom might be rath
by cabalamat 17y ago
> Code must always be "self documenting"
This is in practice very hard to achieve. One reason is that a fully self-documenting name of a functiom might be rather verbose. I'll give an example based on code I'm currently working on. It contained this method definition (in Python):
def varGloLv(self, varp):
Clearly no-one looking at that on its own could tell what it does. What it in fact does is look up a variable, specifically a global one ("Glo") withch is an lvalue ("Lv"). And the parasmeter is the variable name as a Python string. A more self documenting name might be:
def variableLookupGlobalLvalue(self, variableName):
But if I gave all my methods and variables such long names, the code would look terribly verbose and be hard to follow. So instead I use a comment that says what the method does, and specifies the type of its parameters and return value:
def varGloLv(self, varp):
""" lookup a variable, that's global and an lvalue
@param varp [string] the variable name
@return [UBasicType] the value of the variable
"""
- wvenable 17y agoYour original function name is pretty terrible and your alternative is an artificially bad example. If Lvalue implies variable (and possibly variable implies lvalue) then both are not necessary in the name. Var will be universally understood but Glo and Lv would stump anyone not familiar with your personal shorthand. The word lookup is unnecessary. You can still get something quite self-documenting and not all that verbose or long: def getGlobalVar(self, varName): def getGlobalLvalue(self, varName): def varLookupGlobal(self, varName): def lookupGlobalLvalue(self, varName): def globalLvalue(self, varName): ... Nobody says you need to go all Java and make your variable names stupidly long. But small measures towards readability can go a long way to making code self-documenting and easier to understand.
- cabalamat 17y ago> If Lvalue implies variable Lvalue implies something that goes on the left side of an assign statement. An lvalue needn't be a variable, it could be a whole expression, E.g.: a := b; c[x] := d.y; Here, a and c[x] are lvalues. b and d.y are rvalues.
- wvenable 17y agoRight, but in the context of your function an expression is not possible -- you are passing a variable name to a lookup function.