Hi, Habrahabr! In this article I will share my opinion about software development. In information technology I am not so long ago, but I have developed a strong attitude towards development, starting from the names of commits and ending with the clarification of the requirements for the task.
Development
Changes of the same type
Imagine that you got a task in which you first need to develop an optimized solution, and then use it instead of the old one in a dozen files in a project. First you get an appruv that your approach to solving the problem is correct, and then refactor. Decide to do everything at once - you can receive critical comments and edits to the decision to the review code. Then you have to rewrite all the files in which you have applied the new code.
Implementation of tasks
Do not solve the problem “with a saber headshot”, do not make important decisions hastily, even if it seems that your approach is correct. Follow these guidelines:
- Analyze existing implementations in a project or online, refresh the principles and design patterns.
- Do not spend more than 20 minutes solving typical or overly complex problems; this is not effective. Most likely, if you do not find the right approach quickly, the solution is not obvious.
- Ask for help from colleagues, including lead developers.
- Solve the problem within the framework of the subtasks step by step, do not jump over - “I will do the difficult later”. It may well turn out that there are no right solutions, and the existing ones are not suitable and the task should be reconsidered.
- Solve the problem starting with the fundamental things, make sure that the conceptual areas work. It may turn out that individually your functionality is viable, and connecting it together will require crutches or another integrated approach, which will take extra time.
Pull Requests
Title
The name should describe the changes in brief - be short and concise. Follow the header design rules:
- begin with a capital letter
- without a point at the end,
- have an imperative mood.
Ticket-295: Add base cat interface and British cat realization
Description
This section of the pull request should be written correctly in a language understandable to a non-technical specialist, divided according to the meaning, and disclose the changes as follows:
- result in several sentences,
- what preceded the changes
- why and why they needed to be done
- what exactly did you do
- how you implemented it.
The base cats interface was created to provide the common cats functionality and attributes. Also the realization of the British cats was created as the individual one. Our business-analytics have provided for product owner that they want to interact with cats on out platform too, not only with docs. So developers got the tasks to design and implement basic implementation of the cats interface to describe the common patterns of the interaction with it by user. Also the goal was to create one demo cat called British cats (British Shorthair) with its great noses.
reference
In the end, leave links to topics covered in pull request. If another developer needs to better understand the changes, he will be able to look there. Also a few rules:
- briefly describe where the inquiry is sending,
- if possible - throw full links,
- if not, abbreviate with git.io and bit.ly ,
- make a list.
References: • British cats — https://en.wikipedia.org/wiki/British_Shorthair • Cats anatomy — https://en.wikipedia.org/wiki/Cat_anatomy
Commits
Merge commit
When you work on new changes, you do it in a separate working branch. The commits in the working branch are self-documenting changes in a single line.
$ git log --oneline 4336d35 Create cats interface 7bc2ba9 Implement Persian cat realization 5f330fd Add Persian cat documentation ...
When it comes time to make these changes to the default branch, this is done in one big commit with a title and a comprehensive description of what was done and why. The correct practice of merging changes is to use a web-based source code storage system like
Github and
Gitlab .
$ git log --oneline d2ccf1a Ticket-299: Prevent cats graph be stopped unexpectedly (
As a result, the default branch is filled with commits with a detailed description of the changes.
Ticket-299: Prevent cats graph be stopped unexpectedly There was a situation when cats graph is stopped unexpectedly without any verbose information and traceback. The socket connection between two web-servers (back-end and front-end) was successfully debugged and founded the socket library async latent behavior. Implemented: — Create handler for async socket connection as sync. The consumer doesnt specify a condition for ending the while loop and stream, so the application checker in Daphne cleans up the task if the protocol disconnects and the app doesnt handle it. So `channel_layer` is wrapped to `async_to_sync`. — Fix low latency between pushing the cats graph data and its output on the user interface. There was a high coupling between interface class that proxy via a few client to the realization. The separated cats graph message class was created. References: • Socket channel layers — https://channels.docs.io/channel_layers.html • Daphne handle_reply() — https://git.io/fgVzK Issue:
Follow the rules below when making merge commits:
- all changes in one commit;
- the title and blocks of text with different meaning are separated by an empty line;
- Describe the changes: why they were needed, what problem they solve;
- describe each change in the form of a list in detail: go into details and consequences,
- make your decision obvious;
- leave links to help, documentation, forums, discussion of problems;
- refer to topics or pull requests if your changes concern them;
- limit the length of the lines in the message to 72 characters.
Soft skills
Written communication
Developers every day conduct written communication on technical topics, about projects, approaches to solving problems, but they do not always do it well. The person with whom you communicate does not read your thoughts, does not think like you, and does not remember the details of the topic of the sentence you are leading. How to improve this process:
- Follow the rules of spelling and punctuation to delimit the text within the meaning.
- Use line breaks and leave blank lines between unlinked blocks of text.
- Use lists to highlight consistency or label offers.
- Use the services for sharing part of the code or use corporate tools: Pastebin , Github Gist , Codeshare or, for example, in the Slack messenger there is a function in the code or text snippet chat.
- Highlight your own names, important words and details using the built-in to your messenger, markup. Now any modern messengers support the selection of text on the type of this.
- Support the subject of discussion with links to documentation, articles or posts from the forums.
- Do not write and do not show unnecessary information to the interlocutor. For example, do not fill in the screenshot just made with the name in the format of the date Screen Shot 2018-06-23 at 12.17.31 AM , if the interlocutor sees this inscription. Change closer to the Traceback discussion topic during the registration process.jpg .
A responsibility
You grow as a professional not only when you get new experience and knowledge, but also if:
- when solving problems, consult with experts;
- your work can be done better - improve;
- colleagues can do a better job - tell him about it;
- don't know something - acknowledge it and ask for help;
- You listen to the processes, introduce new and do not ignore the problems.
Thank you for taking the time to post. Leave feedback in private messages or comments, I will be glad to discuss.