The purpose of the following document is to present best practices used in our company. Some of the things are mandatory, some of them not. However, it is good to follow them in the name of the team play and good project's architecture.
Every project should start with a new Git repository. Don't leave the project's code only on your machine or on the server. Commit your changes as often as possible. The version control should not act as a file storage or backup utility. It really matters how often you upload changes. Every single moment, you or some of your colleagues, may need to roll back some modification. If there is one commit per day this is not possible. It's also important to add a meaningful message. Something like
fixing bug or
updates doesn't help a lot. It should be clear what you did.
Git has really powerful branch management. It's a good idea to split your work into
development branch. Of course if the project is small one you don't need to do this, but in most of the cases, this is needed. Read about GitFlow and get ideas from there. Keep your master branch up-to-date, valid and working. At every moment, it should be possible to get the code from there and release it on the production server.
README.md file. If you don't like the Markdown format use plain text. The really important thing is to have such file. It should give enough information to everyone so he could setup the project and start working with it. Here are few things that you should put notes about:
- What is this project's scope
- What are the project dependencies (libraries, frameworks etc ...)
- Steps for setupping the project
- Steps for deploying the project
- Tricky parts
- Your name
- Check if your colleagues know something about the technology. Using something that only you understand is a single point of failure.
- Make sure that the chosen framework or library is well documented and there are articles or tutorials which explain how it works
- Consult (if necessary) with your colleagues. Some of them may have bad experience with the technology.
- Make sure that the tools which you want to use are actually installed on the production server. It's really easy to setup something on your machine, but we are not shipping your machine. At the end everything should work on the official server.
Beating blank page syndrome
The blank page syndrome is typical for the writers, but it happens to the programmers too. Very often you are sitting in front of an empty class wondering how to start. There are tons of materials about modular programming, good and well structured code, best practices and so on. You should read a lot and improve your skills over the years. The purpose of this post is not to make you a better developer. It is trying to give you a guidelines. Before to start writing something - THINK. Even if the deadline is tomorrow you still have a chance to produce something good. Plan your work, analyze the given tasks and imagine how your application will look like. Visualize the different components and how they collaborate. There is something which I call brute-force programming. You start typing line after line without thinking about architecture, design patterns or composition. You implement feature after feature and it seems that you are doing a good job. However, this is wrong. Sooner or later your crappy code will start getting buggy and will probably stop working. That's because it is not planned very well and the final product looks more like a spaghetti rather then a software. Here are few tips for beating the blank page syndrome:
- Testing, testing, testing - you should write tests. It is not true that following TDD takes more time. The truth is that it leads to better software. Try it and you will see. Once you start coding something ask yourself "How I'm going to test it?". This question is like a key which opens all the doors. It produces classes with only one responsibility and encourages the modular programming.
- Avoid speculative generality - that's a code smell which you get when you write something just because you think you will need it in the future. And in most of the cases you never use it. Yes, it is difficult to find the balance, but try to keep the abstractions as less as possible. Implement only what you actually need.
In most of the cases we rely on frameworks developed by other people. Some of them are good, some bad, but we should play by their rules. Having this in mind you should follow the coding style provided by the system. If you need to write something custom make sure that it doesn't break some of the existing functionalities. Write in the
README.md file how your code should be setupped, where is the configuration and what is the main application flow.
Avoid global functions or variables. Try to put the things in their own classes. Following this approach you will be able to write tests and of course you will have a better control over your own code.
Keep the external libraries to minimum. There are tons of useful stuff out there, but please, don't use them all. Having a 90K library just to get the value of an input field is not a good idea. It's always good to have less dependencies. It's even better to build a dependency free application.
Keep the configuration in one place and this place to be somewhere in the back-end. It's also good to have at least two configurations. One for a local development and one for the production server. Describe everything into the
In the ideal case you should have an SSH access to the server, log in there and pull the latest changes from the Git repository. This means that the configurations should be nicely split and ignored. If the project is small, don't have a SSH access or there is no Git installed you have to upload the changes via FTP. However, this is really old-fashion way of doing the things. If that happens, please make sure that the master branch in the repository contains absolutely the same files as those on the server. Again, describe the deployment process in the
Be kind and polite with your colleagues and always remember that you work together. Play with them not against them. Try to put yourself in their position and don't judge them. Sooner or later you will be there too.
Always answer on emails, Skype or phone calls. The last one is not mandatory, but try to do it. The feedback is always helpful. Even a simple
Thanks. will do the job.
We all have questions. Try to ask the right person and before to do it, search for the answer. You don't have to spend a whole day on that, but read the brief again. If it is something technical try finding the answer in Google.
Problems. We meet problems everyday. When you are in a position to report something, try to provide a solution and include it in your email. Saying
I can't do this! brings just a stress for you, for the project manager and for your colleagues. Make your life easier. It is much better to discuss the solving of the problem, rather then the problem itself. Also, make sure that you explain the situation very well and you do this as earlier as possible. Don't wait for the deadline to say that you can't run the code on the client servers, because a PHP module is missing.
Be responsible and care about the products which you are working on. The code which you deploy is yours. That's what you are as a developer. Don't leave broken or crappy stuff in the repository. Don't leave comments like
// what the hell is this.
Don't take all the things above as rules. Think about them as tips, good practices or advices. We all know that not everything could be done, but it is nice to think that we are working like that :)
If you want to update this document feel free to contribute here.