He/תקן קידוד

From GnuCash
Revision as of 10:05, 4 June 2021 by Avma (talk | contribs) (פייתון: typo)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
שפות אנגלית עִברִית

כללי

עמוד זה מתאר את סגנון הקידוד התקני בקוד המקור של גנוקאש.

תבנית C

אנחנו בגנוקאש די רגועים בכל הקשור לתבנות הקוד, אך מעת לעת נריץ על הקוד מתבנת בשם Artistic Style (astyle) כדי לנקות אותו. על מנת להפחית את הצורך בשישמוש בכלי זה (זה מבלגן את היסטוריית VCS, במיוחד את "blame"), אנא תבנתו את הקוד שלכם באופן הבא.

באופן כללי, אנא עקבו אחר ההנחיות שב- תבנית GNU למעט השימוש ברווחים, השתמשו בארבעה רווחים במקום שניים, בהזחת כניסה, ו- לא להזיח כניסת סוגרים. לסיכום, פונקציה מתובנתת כראוי תיראה כך:

 guint
 gnc_account_foo (Account *account, gpointer bar)
 {
      Split *baz;
      guint salt;
      if (gnc_split_waldo (baz) > 0)
      {
           salt = gnc_split_pepper (baz);
      }
      return salt;
 }

נא לשמור על שורות קצרות מ-80 תווים. אם לצורך כך נדרשת גלישת שורות, סדרו את משתני הפונקציה כך:

 gnc_account_function_with_a_lot_of_paramters (LongTypeName foo, LongerTypeName *bar,
                                               TypeName baz)
 {
 }

אנחנו לא משתמשים בהפרדה רחבה בין שמות ומשתנים מיושרים, אז אל תעשו את זה:

 void gnc_account_foo               (Account     *bar,
                                     Split       *baz,
                                     gpointer     waldo);
 Split *gnc_account_pepper          (Account     *salt,
                                     Transaction *sausage);

במקום זאת, עשו כך:

 void gnc_account_foo (Account *bar, Split *baz, gpointer waldo);
 Split *gnc_account_pepper (Account *salt, Transaction *sausage);

למען הפרוטוקול, סגנון שורת הפקודה בה אנו משתמשים (astyle גרסה 1.24; גרסאות אחרות עשויות להניב תבנות שונה במקצת) היא

 astyle --indent=spaces=4 --brackets=break --pad-oper  *.[hc]

את ההגיון שמאחורי המשתנים ניתן למצוא ב- דוא"ל זה.

תבנית ++C

++C עוקב אחר הנחיות תבנית C לעיל, עם השינויים הבאים:

  • Namespaces shall be all lower case, and the outermost one shall be named gnc.
  • Identifier formats:
    • Typenames (i.e. class, struct, enum, and POD type-aliases) shall be camel-cased.
    • Function and object names shall be lower-case and shall have words separated by underscores.
    • Preprocessor Macros and enumeration names shall be upper-case with words separated by underscores.

In addition, certain types of variables shall have prefixes denoting their roles:

  • Member variables: m_.
  • Static member variables (a.k.a class variables): c_.
  • Static constants: k_.
  • Free static variables: s_. Free static variables means statics which are not local and not members of a class or struct, regardless of scope.

תבנות אחר:

  • Single-line standalone comments can use either C++ style or C style. End-of-line comments should always use C++ style. The preferred style for multi-line comments is currently under discussion.
  • Headers and implementation files should be named for the class they declare or implement. In general any file should declare or implement only one class.

הנחיות קידוד

  • Write modern, idiomatic C++ using the new features of C++11; use the -std= CXXFLAGS value in configure.ac to see if you can use features introduced in C++14 or C++17 (as of this writing you may not). In particular:
    • Prefer curly braces for initializers and auto for variable declarations.
    • Declare and initialize variables in one statement at the point that they're first used.
    • Use templates instead of copying code and especially instead of preprocessor macros.
    • Prefer passing references to pointers.
    • Do not ever pass void* (aka gpointer) in C++ code. Use templates or class hierarchies to enforce type safety.

Framework

Gnucash is a Gtk+ project. It's design is object-oriented. The current object orientation is implemented mostly with Gnome's GObject C-language framework and makes heavy use of GLib. While this is a rich eco-system, it brings with it a huge number of dependencies which makes GnuCash difficult to port to other operating systems. Consequently the developers have decided to migrate all of GnuCash except the GUI to C++. No new GObject or GLib-dependent code should be written; instead use C++, the C++ standard library, and Boost libraries.


Guile ו- Scheme

Gnucash is partly implemented in a Scheme dialect called Guile. (It was originally written mostly in Guile, but that implementation was largely replaced with C several years ago.) In particular, the reports system and part of the business system are written in Guile. To support that, most of the core "engine" API is wrapped and accessible from Guile.

Ideally reports and infrastructure code will be coded using a lisp-specific editor such as Emacs. This will facilitate the indenting of parentheses, which will greatly ease readability and maintenance. Emacs coding style is very useful.

Rules for infrastructure code and reports:

  • most reports should be self-contained
  • a function designed for multiple reports may be added into infrastructure code e.g. report-utilities.scm but must be documented properly.
  • aim to create adequate tests using srfi-64
  • aim for a maximum line width of 78.

מנשק משתמש חזותי

ראו GUI Guidelines‎‎.

פייטון

התקן הוא PEP 8 -- Style Guide for Python Code.