If there's one thing you can do yourself a lot of fun with, it's conventions. Huh, conventions? Aren’t that these long and boring lists of things you need to comply with, from variable names to comment structure? Which you never ever seem to be able to adhere to in full? Yes, that’s what I mean!
There are two main reasons why conventions are important:
They provide more “thinking space”. What if you had to come up with a variable naming convention every time you created one? What if you had to decide how to format a function header on every occasion you started one? You don’t want that. Following a pattern, aka convention, is way easier to your working memory, already filled with the many intricate details of a program’s logic.
It boosts comprehensibility. Being able to see what this variable name stands for,
where a functions starts and ends, what else belongs to what
if, helps a lot in understanding a piece of software.
I admit, conventions have a bad name. Sometimes they’re used to wrap long red tapes around programming efforts, which reduces all the fun. But applied properly they can absolutely help improving the comprehensibility of the code. How can we make them effective?
There should’t be too many of them. It must easily fit in your head. So maybe a list of one or two pages long?
They should’t be regarded as absolute. When following a convention leads to ridiculous long names/indenting/indecipherable code/overly long functions/… (cross out what does not apply), either change the convention or decide that this is an exceptional case and break the rules.
And yes, you have to get used to them. If the list isn’t too long and the conventions more or less make sense, they’ll soon become a habit.
With respect to comprehensibility, what are the basic things important enough to have a convention about?
Names of variables, functions, data structures, etc.: Pick something and stick to
it. I personally prefer the lower-case-with-hyphens convention but
there’s nothing sacred about it. The lowerMixedCase,
UpperMixedCase, lower_case_with_underscores or whatever are
just as good. You can also use multiple naming styles for different things in your
program, but don’make choosing the right one too complicated!
The only thing I would definitely not recommend is using
something without some kind of word separation. The worst example probably being
ALLCAPSWITHOUTANYSEPARATORS: too hard to read and understand.
Layout: Things like indentation, whitespace, empty lines, separators, comment styling, etc. Choose something and try to keep the code consistent. More about this in the section called “The rhythm of the code”.
You can make it easy on yourself here: find out what the pretty-print functionality of your IDE is capable of, and use that as (part of) your layout convention…
Commenting: What to write comments about, how they’re formatted, etc. See the section called “Comments? What comments?”.
Filenames and directory structures: Again, pick some naming convention. Don’t
forget to standardize the extensions (is an XQuery script
*.xq, *.xql or *.xquery?). If there
isn’t already one, try to invent a convenient directory structure, using
standardized names, that fits the bill.