Developer Guidelines For Big Projects

Benefits

While working in software industry you will find a lot of standards, best practices, recommendations, guidelines, etc.

A grade of uniformity in big software projects helps every involved person to switch from one part of the project to another part. As well in audits, the exchange of developers between parts of the projects and to get an overview over a big project it helps significantly to use a kind of standards written down in developer guidelines.

A word in advance

A word in advance: The aim of developer guidelines should not be process guidelines that every one has to follow. There are different gradations like: you have to follow this naming convention, best practice is to use linters, you should decide with your team if you follow Branching model A or B and you have to describe it in your (architecture) decisions.

The following suggestions are not complete for developer guidelines. You need to verify and adopt the guidelines. Examples for needed adoptions is because of quality requirements of your customer, regulations of your company or legal requirements of the company where the software has to run.

Mostly the software architects of your customer and stakeholders wants to be involved and verify the guidelines.

Content Of Developer Guidelines

Developer guidelines are not only about code. It’s much more. It’s the ecosystem around the process of coding.

Coding Guidelines

In short the coding guidelines have to ensure that developers produce clean and maintainable code. It has to contain requirements and best practices for:

• naming conventions.
• package structures and folders.
• natural (human) language for comments, class names, variable, etc.
• recommendation that the code should SOLID rules, when possible.
• how to handle errors.
• A list of preferred coding languages.
• How much comments on code is expected.
• Use of linters.
• Test driven development and unit tests expectations.
• How often to push code to the central repository.
• Details on code reviews. Who will do code reviews? How often? When? What is the amount of code reviews?
• Using of code quality scanner like Sonarqube.
• etc.

Use of tools and software for coding

Points to think about are:

• Where to push the code: Github, Gitlab, yours company Versioning System?
• Recommended IDEs.
• Where to push your artifacts, where to retrieve dependencies. Use of something like Artifactory.
• Where to find documentation. Where to put documentation.
• Quality scanners. Linter(s). Prettier(s).
• Use of security scanner(s).
• Tools to generate documentation.
• etc.

Software Versioning System and Branching

Nowadays the versioning system will be mostly git. And while using git you should suggest a branching model or require from the teams of your project to decide for a branching model. The teams have to explain in a decision document which branching model they choose and why. An example of a branching model is feature-branch-workflow.

When using feature branches you need to decide about your merge strategy. One possibility is to create for every change a merge request.

Code quality and security

One possibility to ensure code quality is at Merge request. Merge requests can be reviewed in two parts.

In manual peer reviews by another developer to share knowledge across the team.

In automatic reviews by using a pipeline in the merge requests that invokes build, test and different scanners.

Unit Testing, e2e Tests

One point of discussion is often the test coverage. An issue with test coverage is that it does not show the quality of tests.

If developers have problems to implement unit tests it could be a sign that the code needs to be refactored. With developer guidelines you can force that you don’t run in a problem with bad code design or low quality unit tests. It is not enough to measure the test coverage.

For end to end tests you can define in developer guidelines which frameworks are the favorites in the project to force consistency and reduce the number of used techniques. E2E tests are recommended part of code development.

May you think in the developer guidelines as well about performance tests.

You can refer in developer guidelines to the test pyramid.

Security

The guidelines needs to explain how security checks happen. Are there security guidelines of your company or your customer or from someone else? Is there an auditing to ensure what security is implemented in correct way. Are there any tools or scanners used to check the security and the security of used dependencies?

How do the teams handle upgrades of dependencies? Is there any tool used like renovate?

How to you check that the used frameworks and packages are secure?

You can suggest to use for Node JS projects ‘npm audit’.

Projects that are open for access from the internet a periodic penetration test should be recommended.

Login process and password rules

The developer guidelines can specify which kind of login can be used. Password rules and the handle of unsuccessful login attempts are other things that may should be described.

Content of the code repository

What needs to be included in the teams code repos? There are many advices for the content of the readme file. Which information has the readme file to contain. Minimum is that the readme file tells about how to build and test the software.

Are there other expectations about the content of the code repository like documentation in asciidoc format?

Will be configuration files in the root directory of the teams repo? Where to find configuration for linters, code quality scanner, deployment configuration, build configs, etc.?

Logging

When and what needs to be logged. Which logging framework is used? It should be decoupled in one class.

Monitoring

How is monitoring done for this part of the project. How alarms will be defined? Which data is important for monitoring?

From functional perspective you can monitor the count of users logged into the system.

From technical monitoring perspective you can count how many wrong password phrases were used by one single ip address and set an alarm when it seems that someone try to hack your application.

You should define what is expected for health checks. Should they only reply a http 200 or more information like the status of the database connection or the status to other interfaces?

UI Design Guidelines

Usually there are corporate design guidelines that the projects have to follow for frontends. If there is nothing you can give advice to follow official guidelines like Google UI design guidelines like material design.

The colors and other specific design elements should be predefined for all teams from UX experts to ensure a unique look across the project.

API Design Guidelines

Many companies has been started to create API design guidelines. Try to find these and put a link to them for your developers.

If there are no companies API design guidelines you can suggest to refer to others. There are open API design guidelines documented like the ones from Zalando.

Documentation

Where to find business and architectural documentation? Where to put the documentation and what is the expected amount? Try to use graphical overviews and different form of diagrams.

The aim of documentation should be to give an overview and references to know where to find what. Describe only things that cannot be described in code.

The truth is always the code, don’t allow a copy&paste of code into documentation.

Ensuring compliance with the guidelines

It should be described how to ensure that the teams follow guidelines. One possibility is to set up periodic audits. To keep it open and comparable checklists about what is the content of an audit can help. I am not a fan of checklists, but they can help in the manual process.

Try to automate as much as possible and describe that. Even if you reference that the automation of compliance checks happen in pipelines.

Exchange knowledge across teams

While working in a huge project with several teams there should be some exchange between the teams implemented. Like periodic knowledge exchange and presentations of solved problems and how things are implemented.

Developer team meetings should be limited to technical attendees only. Otherwise the exchange of knowledge between technicians will be decreased.

Other Thoughts?

For sure the listed points above are not complete for developer guidelines and may some of them are too much for some clients and companies.

I am happy about your feedback. Please let me know if something should be explained more clearly.