Efficient code submission: Best practices to avoid future problems

Bad code submission can cause great trouble. Have you ever struggled to pursue the intent of a specific change, or the status of the current code? The correct way to submit code can effectively avoid these difficulties. This article will dive into the best practices of software submission.

Core points

• Correct code submission can prevent confusion and save future time. Submissions should be atomic, dealing with only one specific issue at a time, rather than bloatedly affecting a large number of files and adding multiple features.
• Good submissions should be clear, insightful and atomic. The commit structure should contain types or components, clear topics, and optional body text to provide more context or details.
• The issue should be handled in the submission information, using the keyword and question ID number. This facilitates tracking of tasks, improvements, and errors in the project.
• No matter the size of the team, correct code submission is crucial to good project management. It maintains the integrity of the code base and makes it easier for other developers to understand and process the code.

Why bother?

If you have already stored your project on GitHub, you might think the file is safe and you can extract the changes whenever you need to update your code, which is enough. All of this may be true. But let's see what potential problems can be avoided by putting in more effort and what additional benefits you will get if you do this.

Single-only work should be avoided in teamwork or personal work

The above reasons usually come from developers who are used to working alone. But when they need to share code with others, things get messy and require a lot of explanation. Remember, our job is more than just writing code. We also need to manage things, which requires a certain degree of organization and methodology. While teamwork is more likely to expose problems caused by poor organization, we can also benefit from better approaches, even when working alone.

Atomic submission and bloated submission

We all need to undo a small change, only to find ourselves searching for it in a huge commit that changed dozens of files and added multiple features. If the change is in a single commit that only handles that particular issue, rolling back will be much easier.

Cluttered, bloated way

In this example, we can be sure that many files are affected. In addition, the "new components" information does not tell us much information - such as which components, which functions of these components, and whether the functions are new or refactored. Also, are any existing errors resolved?

<code>git add *
git commit -m "new components"</code>

This information will be very important when we need to change or restore something. We'll try to find a pin in a pile of hay, and we might end up looking at the code base and spending valuable time debugging.

Atomic Way

<code>git add *
git commit -m "new components"</code>

Now we are starting to get a better idea of ??what happened to the that commit.

The trick is that We can commit changes semi-automatically as part of the workflow. That is, perform a work block that performs very specific operations (implement specific functions, fix errors, optimize algorithms), conduct tests (write unit tests if needed), add descriptions when memory is fresh, and then Submit now. Repeat this process.

Good submission structure

These rules are not set in stone, but they can help you evaluate what a good submission might look like:

Clearness: There is no doubt about the work done to submit changes.
Insightful: clearly describe the functionality of the code, provide links or additional information if necessary, and mark errors or issues being processed.
Atomicity: Only deal with one thing at a time (consider a "working block", which can be 20 minutes to 2 hours, or even 2 minutes if it's a quick bug fix).

Let's look at a template and break it down:

<code>git add ui/login.html static/js/front-end.js
git commit -m "validate input fields for login"</code>

Type, component or subsystem

This will be a set of software project features that can be combined together. For example, the so-called types in AngularJS, or the so-called subsystem in SrummVM.

(required) topic

The topic is a simple and straightforward description of the work done by the submission so that everyone can see it at a glance.

In terms of topic format, I usually follow the following simple guidelines:

Use imperative sentences ("change" instead of "changed")
Don't capitalize the first letter
Do not add periods at the end (.)
Add "(…)" if there is an optional body

(optional) text

Sometimes we need to provide more details than suitable in the subject line to provide context, such as when fixing persistent bugs, or when cracking algorithms.

In these cases, you can simply enter a double newline character (so that the subject is used as a title) and then enter the required information.

Don't forget to deal with the problem!

Finally, there is another problem to deal with the problem (pun!). Any decent large and medium software development project should use issue trackers to track tasks, improvements, and errors – whether it’s Atlassian Jira, Bugzilla, GitHub’s issue trackers or whatever.

Problem Management

If you don't know, most systems can manage issues directly from the submission information!

You can:

Close/Solve the Problem

If the problem was closed before, reopen the problem
If the function is postponed to a later date, then the issue of retention
• Just use these keywords and the ID number of the question.

In addition, you can still cite the question as a way to provide context, even if you don't want to modify its state - for example, "See #12".

All of these references will be visible to anyone who opens the issue on the tracker, which makes it easy to track the progress of a given task or error.

Summary

You won't always do it right (not myself!). Things can get messy, and sometimes you don’t follow the rules you set for yourself or your team – it’s part of the process. But hopefully you know that by simply doing some upgrades to your workflow, you can be organized and save time for you and your team in the long run.

I also learned from experience that the project involves ten developers and is still handled entirely by you, which makes it almost impossible. In short, submitting code changes in the right way – this is a key part of good project management.

Further reading

• Tell stories with Git history. An interesting article by Seb Jabocs on FutureLearn.
• Angular's Submission Information Guide. Even if you don't use Angular, this is a helpful reading.
• FreeBSD Submitter Guide. If there is one, here is an in-depth guide on the topic.
• How to correctly organize files in your code base and avoid confusion. We explain how to organize documents for large and small projects, providing some easy-to-follow best practices.
• Quick Start Git. This concise guide is designed to help beginners quickly master Git in one weekend.
• Professional Git. Wiley's book goes a step further, providing developers with in-depth research they need to become Git masters.

FAQs (FAQ)

• What is the difference between a code base and a source code?

Codebase refers to the entire collection of source code used to build a specific software or application. It includes all versions of code and branches. On the other hand, the source code is part of the code base currently being processed. It is code written in a programming language and then compiled into an executable program.

• How does commit changes in the code base work?

Submitting changes in the code base involves changing the source code and then saving those changes to the code base. This process is usually done in a version control system like Git. When you submit your changes, you are actually taking a snapshot of your work at that point in time. This allows you to track changes you made and restore to previous versions if necessary.

• What is the importance of submitting changes in the right way?

Commit changes in the right way is critical to maintaining the integrity of the code base. It ensures that the code base is kept clean and easy to manage, making it easier for other developers to understand and process the code. It also helps track changes and identify when and where errors are introduced into the code.

• What are some best practices for submitting changes?

Some best practices for submitting changes include making small, incremental commits, writing clear and descriptive commit information, and testing your changes before submitting. It is also important to sync your local code base with the main code base regularly to avoid conflicts.

• What is a version control system and what does it have to do with the code base?

Version control system is a tool that helps manage codebase changes. It tracks every modification to the code in a special type of database. If an error occurs, developers can rewind time and compare earlier versions of the code to help fix the error while minimizing the impact on all team members.

• How to avoid conflicts when submitting changes?

Clashes can be avoided by regularly synchronizing your local code base with the main code base. This ensures that you are always working on the latest version of your code. It is also important to communicate with your team, making sure everyone is aware of the changes being made.

• What is the role of code bases in software development?

Code library plays a crucial role in software development. It acts as a central repository for all source code, allowing developers to work together and handle different parts of the software at the same time. It also helps track changes and maintain project history.

• What is the difference between a code base and a code repository?

Code library refers to the entire collection of source code of the software, and the code repository is where this code is stored and managed. A code repository can contain multiple code repositories, usually managed by a version control system.

• How to make sure my submission is meaningful and useful?

To make sure your commits are meaningful and useful, it is important to make small, incremental commits, each commit has its own specific purpose. Each commit should represent a single logical change. It is also important to write clear and descriptive submissions that explain the changes made and why.

• What is the relationship between the code base and the build?

Building is the process of converting source code from a code base into executable programs. The code base is the input to the build process, and the output is a software product that can be installed and run on the computer. The build process can include compiling code, linking libraries, and packaging software for distribution.

The above is the detailed content of Commit Changes to Your Codebase the Right Way. For more information, please follow other related articles on the PHP Chinese website!