Guidelines for developers

From Double Commander Wiki
Jump to: navigation, search

Here is a list of guidelines for developers to follow.


Writing code

Coding style

  • 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.

Writing comments

  • 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. The en 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
    // -- Daniel's code ends -- 05.09.2001

Designing GUI

  • 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.

Commiting to SVN

  • 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 >
  • 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.
Personal tools