Grappus Development Guidelines

The objective of this website is to follow and maintain a uniform convention and rules to follow while developing which is applicable across all teams.

Best practices

Common best practices that we intend to follow:

  1. Use Git properly: It helps in maintaining proper workflow and keeps track of changes in source code over time.
  2. Follow standard naming conventions.
  3. Use file templates in your IDE to avoid doing the same thing, again and again, such as Live templates in Intellij.
  4. Follow common practices and IDE and Indentation settings across the team.
  5. Put comments in ad-hoc logic.
  6. Follow the latest architecture pattern.
  7. Use RX where ever possible to save time and write less code.
  8. Set up CI/CD for ease of integration and distribution of builds.

Writing Meaningful Names:

The following is an excerpt from Clean Code: A Handbook of Agile Software Craftsmanship (Robert C. Martin).

Names are everywhere in software. We name our variables, our functions, our arguments, classes, and packages.

Use Intention-Revealing Names:

It is easy to say that names should reveal intent. Choosing good names takes time but saves more than it takes. So take care of your names and change them when you find better ones. Everyone who reads your code (including you) will be happier if you do.

You should name a variable using the same care with which you name a first-born child.

The name of a variable, function, or class, should answer all the big questions. It should tell you why it exists, what it does, and how it is used. If a name requires a comment, then the name does not reveal its intent.

int d; // elapsed time in days

If a name needs a comment to describe itself then it is not a good name.

The name d reveals nothing. It does not evoke a sense of elapsed time, nor days. We should choose a name that specifies what is being measured and the unit of that measurement:

int elapsedTimeInDays; 
int daysSinceCreation; 
int daysSinceModification; 
int fileAgeInDays;

Add Meaningful Context:

There are a few names which are meaningful in and of themselves—most are not. Instead, you need to place names in context for your reader by enclosing them in well-named classes, functions, or namespaces.

Imagine that you have variables named firstName, lastName, street, houseNumber, city, state, and zipcode. Taken together it’s pretty clear that they form an address. But what if you just saw the state variable being used alone in a method? Would you automatically infer that it was part of an address?

Writing Functions:

Small!: The first rule of functions is that they should be small. The second rule of functions is that they should be smaller than that.

Do One Thing: Functions should do one thing. They should do it well. They should do it only.

Function Arguments: The ideal number of arguments for a function is zero (niladic). Next comes one (monadic), followed closely by two (dyadic). Three arguments (triadic) should be avoided where possible. More than three (polyadic) requires very special justification—and then shouldn’t be used anyway.

When a function seems to need more than two or three arguments, it is likely that some of those arguments ought to be wrapped into a class of their own.

Whenever you are doing some conditional operations such as switch statements and inside that, if any operation takes up more than 3 lines, extract that operation into a separate meaning function.

Prefer Exceptions to Returning Error Codes:

Try to not to return a default value if any condition does not satisfy the pre-known clauses, return an exception instead so that the caller of that function can handle unknown cases accordingly.

Comments:

Nothing can be quite so helpful as a well-placed comment. Nothing can clutter up a module more than frivolous dogmatic comments. Nothing can be quite so damaging as an old crufty comment that propagates lies and misinformation.

It is sometimes useful to provide basic information with a comment but most of the time they can be eliminated by the use of good names. For example: 

// Check to see if the employee is eligible for full benefits 
if ((employee.flags & HOURLY_FLAG) &&
(employee.age > 65))

Don’t Use a Comment When You Can Use a Function or a Variable. The above is comment is unnecessary and can be easily avoided by extracting to a separate function.

if (employee.isEligibleForFullBenefits())

TODO Comments:

TODOs are jobs that the programmer thinks should be done, but for some reason can’t do at the moment. It might be a reminder to delete a deprecated feature or a plea for someone else to look at a problem. It might be a request for someone else to think of a better name or a reminder to make a change that is dependent on a planned event. Whatever else a TODO might be, it is not an excuse to leave bad code in the system.

Every TODO comment should include the following things: 1. Name of the person writing the TODO. 2. Why is he writing a TODO? 3. When does he expect to remove it?

Commented-Out Code

Few practices are as odious as commenting-out code. Don’t do this!

InputStreamResponse response = new InputStreamResponse();
response.setBody(formatter.getResultStream(), formatter.getByteCount());
// InputStream resultsStream = formatter.getResultStream();
// StreamReader reader = new StreamReader(resultsStream);
// response.setContent(reader.read(formatter.getByteCount()));

Others who see that commented-out code won’t have the courage to delete it. They’ll think it is there for a reason and is too important to delete. So commented-out code gathers like dregs at the bottom of a bad bottle of wine.

Formatting:

When people look under the hood, we want them to be impressed with the neatness, consistency, and attention to detail that they perceive. We want them to be struck by the orderliness. We want their eyebrows to rise as they scroll through the modules. We want them to perceive that professionals have been at work.

You should take care that your code is nicely formatted. You should choose a set of simple rules that govern the format of your code, and then you should consistently apply those rules. If you are working on a team, then the team should agree to a single set of formatting rules and all members should comply. It helps to have an automated tool that can apply those formatting rules for you.

The Purpose of Formatting: First of all, let’s be clear. Code formatting is important. It is too important to ignore and it is too important to treat religiously. Code formatting is about communication, and communication is the professional developer’s first order of business.