While everyone has his/her own preferences, working as a team - to build well designed products - means to agree on how we will write clean, readable and maintainable code. Some of
these conventions might take some time for you to get used to but they are not to be blindly followed; strive to understand these and ask when in doubt.
General Best Practices
-
Don’t duplicate the functionality of a built-in library.
-
Don’t swallow exceptions or “fail silently.”
-
Don’t write code that guesses at future functionality.
-
Exceptions should be exceptional.
-
-
Break long lines of code. The number fo characters depends from each stack.
-
Place comments above the concerned line(s). Do not inline comments.
-
-
Use an empty line between methods.
-
Use spaces after commas, after colons and semicolons, around { and before }.
-
Use Unix-style line endings (\n).
Naming
-
-
-
Name variables, methods, and classes to reveal intent.
-
Prefer the singular of a word over its plural version.
-
Avoid object types in names e.g.
user_array
,
email_method
,
CalculatorClass
,
ReportModule
.
-
Prefer naming classes after domain concepts rather than patterns they implement e.g.
Guest
vs
NullUser
,
CachedRequest
vs
RequestDecorator
.
-
Suffix variables holding a
type
with their
_type
e.g.
user_factory
,
user_spec
.
-
Treat acronyms as words in names, even if the acronym is the entire name.
XMLHTTPRequest = '';
class HTML
end
XmlHttpRequest = '';
class Html
end
Organization
-
Order methods so that caller methods are earlier in the file than the methods they call.
-
Order methods so that methods are as close as possible to other methods they call.
Object-Oriented Design
-
-
Avoid long parameter lists.
-
Limit collaborators of an object (entities an object depends on).
-
Limit an object’s dependencies (entities that depend on an object).
-
Prefer composition over inheritance.
-
Prefer small methods. Between one and five lines is best.
-
Prefer small classes with a single, well-defined responsibility. When a class exceeds 100 lines, it may be doing too many things.
Relational Databases
-
-
Constrain most columns as NOT NULL.
-
In a SQL statement, only select columns you need (i.e., avoid SELECT table.*).
-
Use an ORDER BY clause on queries where the results will be displayed to a user, as queries without one may return results in a changing, arbitrary order.
-
Use uppercase for SQL key words and lowercase for SQL identifiers.
Non-relational Databases
-
Do not try to make it do every job you have. For transaction-based applications with fixed entities, relational databases are better suited.
-
Avoid deep nesting of data. Instead, data should be de-normalized/flattened as much as possible.
-
Beware of update operations. Most databases offers
SET
and
UPDATE
operations that do not behave the same.
API Design
-
We generally follow REST and
JSON API. In addition, before designing a new API, review the recommended practices outlined in
Heroku API Design Guide.
-
Version endpoints e.g.
v1/
,
v2
.
-
Document the endpoints and parameters. Online tools like
Apiary or
API Docs can be used.
Code maintenance
-
Use
TODO to mark incomplete parts of code.
-
Use
FIXME to mark parts of code that are broken or cause bugs.