Readable Code

Avoid commenting on the obvious

Follow the Inline Documentation Standards to document your code. 

Developers should document your code as detail as possible. However, please also keep in mind that we shall not comment on the obvious. If you find your inline comment is explaining “what” the next line of code is doing, it is very likely you don’t need the comment at all. When adding inline comments, think in terms of “why” is more suitable.

The docblocks and inline comments are the tools we use to remind our fellow developers there is important information for them. If you stuff the docblocks with a 500 word essay, or add inline comments everywhere, the readers will lose track of what is important and what is not.

Using early return

Early return is probably the most powerful trick for developers who want to improve the readability of their code, with the least time needed to invest. 

Once implemented, you will also get another benefit that you don’t have to write another else block in your code ever. Plus, it also helps refactoring complex conditionals.

Avoid using abbreviations

It may feel appealing to use abbreviations in your code, when naming a variable, a function or even a hook. You’re not alone, we see abbreviations everywhere.

However, considering everyone has a different cultural background and English may not even be your fellow developers’ primary language, we encourage not using abbreviations, but the full term of words as best as we can.

Easy cases are like, when naming a function that relates to calculations, we name it as text_calculations instead of text_calc, or any other form of abbreviations.

More complicated cases are how we treat brand or product names. For example, can we shorten Gravity Flow as GFlow or Gravity Perks as GPerks? 

There seem to be too many case by case scenarios and even when I searched through the codebase of the Gravity Forms Add-Ons and third-party Add-Ons, I didn’t see a concrete pattern there. For example, Gravity Flow uses both gravityflow and gflow as prefixes and Gravity Perks uses gperk and gperks (but GWPerks as the main class name), while Gravity Forms itself has gform, gf and gforms. This actually makes me more inclined to not to use abbreviations because you may end up having several variations of it.