In the right language, implemented the right way, code can be nearly as readable as the comments, modulo the function names used by the underlying APIs. Not that this necessarily means the should necessarily be removed: they're still a useful check that what is implemented matches the intention. But when possible, a commented piece of code should be structured so that it clearly implements the idea in the comment, and only that idea. For instance, I think that your example code could be improved by doing all the filtering (on both scope and currency) in the first loop, so that the second loop doesn't need to both make the change (as indicated by your comment) and update the total (which isn't even mentioned in the comment).
As an example of what is possible in modern languages, here's a python 2.4+ translation of your code with the pseudo-hungarian prefixes stripped from variables. I assume that the abbreviation "CCy" for currency is standard across your code base and thus obvious for anyone working with this code. I realize that the list comprehension syntax used in the first 2 lines of code--and the generator expression passed to sum()-- might not be completely readable to someone who doesn't know the language, but that's true for the idioms of any language (and I assure you, they become very readable after using them for a short while).
# get securities in current scope that have the relevant settlement currency securities = [s for s in allSecurities if
s.currentScope()==enScope and s.settlementCCy()==sCCy]
# apply the change to each of these securities for s in securities: s.makeAChange(newValue)
# compute a total of the new market values for these securities total = sum(s.marketValue() for s in securities)
# handle case of account going short (i.e. total is negative) if total < 0: account.handleShortChange()
You may not have the luxury of ditching VB for Python, but I wanted to illustrate how a language designed for readability really makes a difference.
One final point: Code should be written for readability first, and efficiency only where it is significant. Not to say that you should write grossly inefficient code, but since most code is not in the inner loop, it usually makes sense to write code in the most readable way unless you know it to be performance critical. If you can make it more efficient without sacrificing readability, all the better. So I don't believe you need to give disclaimers about looping over your collection twice instead of just once when illustrating a point about readability. Similarly, I make no apologies about my code's 3 loops. If the code is performance critical and loop overhead is really significant, it is trivial to transform it to something like the following:
# initialize new total value of securities in current scope, having the # relevant settlement currency total = 0
# for each security in current scope having the relevant settlement currency... for security in allSecurities:
if s.currentScope()!=enScope or s.settlementCCy()!=sCCy: continue
# apply the change to the security
for s in securities: s.makeAChange(newValue)
# update the total to reflect the market value of this security
total += s.marketValue()
# handle case of account going short (total is negative) if total < 0: account.handleShortChange()
Slashdot Mirror
As an example of what is possible in modern languages, here's a python 2.4+ translation of your code with the pseudo-hungarian prefixes stripped from variables. I assume that the abbreviation "CCy" for currency is standard across your code base and thus obvious for anyone working with this code. I realize that the list comprehension syntax used in the first 2 lines of code--and the generator expression passed to sum()-- might not be completely readable to someone who doesn't know the language, but that's true for the idioms of any language (and I assure you, they become very readable after using them for a short while). You may not have the luxury of ditching VB for Python, but I wanted to illustrate how a language designed for readability really makes a difference.
One final point: Code should be written for readability first, and efficiency only where it is significant. Not to say that you should write grossly inefficient code, but since most code is not in the inner loop, it usually makes sense to write code in the most readable way unless you know it to be performance critical. If you can make it more efficient without sacrificing readability, all the better. So I don't believe you need to give disclaimers about looping over your collection twice instead of just once when illustrating a point about readability. Similarly, I make no apologies about my code's 3 loops. If the code is performance critical and loop overhead is really significant, it is trivial to transform it to something like the following: