Guidelines for developers
Alexander Koblov edited this page Jun 17, 2023
·
3 revisions
Here is a list of guidelines for developers to follow.
- Generally there is no specific coding style decided. Use the style of the surrounding code.
- Use spaces as tabs. Tabs are usually inconvenient when used in multi-developer environment because often each person uses different size of tabs. Formatting of code will usually look wrong when tabs and spaces are mixed. See this picture on how to setup Lazarus IDE. If you use different editor than IDE set it up accordingly.
- Comments should be written in English. It doesn't have to be perfect English only just so that other people can understand. If you don't know a word of English maybe it is possible to write comments in a different language but they might be translated into English anyway by other developers.
- Comments describing functions, classes in the
interface
section are usually written with{en ...}
marking. Theen
stands for English language. It is used by FPDoc to generate some documentation. In the implementation section use normal comments. - Write comments for code that might not be immediately understood by others. If you fix a not obvious bug, use code for specific circumstances, make assumptions that are not easily deductable write a few words explaining why, not neccessarily what the code does.
- If something is not implemented yet but is intended to be mark it as
ToDo < what is necessary to complete and possibly how >
This might be a helpful hint to whoever will be completing the code on how to do it. - Do not write comments with your name and/or date denoting which code you have added and when. Double Commander uses version control system for development which can already tell you who wrote what and when. If you write patches and don't have SVN access your name is usually included in the commit message or it can be added to the contributors list. Following example of comment is not appropriate:
// -- Daniel's code begins -- 05.09.2001 if not DanielWroteThis then Exit; // -- Daniel's code ends -- 05.09.2001
- The name of a component (Button, CheckBox, etc.) should reflect its type and application. For example button "Delete" should be named "btnDelete", panel "Buttons" should be named "pnlButtons", etc. Look how components are named in other forms if you're not sure.
- When you design a GUI remember that size of each control may be different for other people. Usually size depends on system settings, font size, DPI setting, theme being used, accessibility settings. When designing you should use following mechanisms:
- Autosize
- It is best to autosize all controls unless you intend to restrict the size of the control to specific values, you use a specific font or specific size of the font. If you want to autosize a group of controls but want them to have the same size as a whole put them inside a TPanel and autosize the controls as well as the panel. You can at the same time use ChildSizing property of the TPanel for some additional alignment within the panel. Use BorderSpacing and/or Constraints of each control and the panel to resize them if they are initially too small.
- In cases where the user is allowed to resize a form autosizing it might conflict with the size saved after resizing; in such cases don't autosize the form. It would be helpful to autosize the form the first time it is displayed and yet restore the size that the user sets later. But such mechanism isn't implemented yet (basically we don't know when the size of the form exist in the session file).
- Anchors
- Design the GUI layout using anchors instead of manually putting the controls at specific coordinates on the form. This allows the controls to be moved correctly after autosize phase. Each control should generally be anchored to its parent or a sibling control. Pay attention when autosizing is used, so that you leave the control unanchored on the side where the control should be resized.
- Align
- Instead of anchors sometimes it may be easier to use Align instead. If you have more than one control usign the same alignment there are specific rules that say which control is first, second, etc. See Align on Lazarus Wiki for more info. If the order of alignment causes problems align a single TPanel, put all the controls inside and anchor them one to another.
- ChildSizing
- ChildSizing is a simple layout manager which you can use for some automatic alignment of controls, for example a bunch of checkboxes or buttons or when you have a few rows of labels with edit boxes. See Layout on Lazarus Wiki for detailed explanation on how to use it.
- Autosize
- Use
git rebase
to have linear history - Use prefixes in commit messages
- When adding a new function
ADD: < what has been added >
- When correcting an error
FIX: Bug < [bug number from bugtracker] > [description]
- When removing code, files
DEL: < what has been removed >
- When updating algorithm, function etc.
UPD: < what has been updated >
- When adding a new function
- It is possible to commit even if added function (module) doesn't yet fully work, however the code must compile successfully and shouldn't prevent other functions (modules) from working correctly.