From d23cb38a9bfd1e6c17c3b0e4be70a832d1601db7 Mon Sep 17 00:00:00 2001 From: Hiroshi Miura Date: Tue, 28 May 2024 08:03:58 +0900 Subject: [PATCH] docs_devel: update coding sytles (#1042) * docs_devel: update coding sytles - Improve readability by splitting sections - Add link to NetBeans GUi builder manual - Recommend MVC structure with examples - Add explanation of API deprecation Signed-off-by: Hiroshi Miura * docs_devel: update coding sytles - Add sub sub section in GUI design section - Add warning to check editor generated source Signed-off-by: Hiroshi Miura --------- Signed-off-by: Hiroshi Miura --- docs_devel/docs/30.CodingStyles.md | 78 +++++++++++++++++++++++++++--- 1 file changed, 70 insertions(+), 8 deletions(-) diff --git a/docs_devel/docs/30.CodingStyles.md b/docs_devel/docs/30.CodingStyles.md index c9ea7384c7..5f74cbae0f 100644 --- a/docs_devel/docs/30.CodingStyles.md +++ b/docs_devel/docs/30.CodingStyles.md @@ -2,6 +2,8 @@ OmegaT project uses following coding style rules and coding policy. +## Code Style Basics + * Each java file has a GPL3 copyright header. OmegaT has a unit test to check header. * Source code has a maximum 120 characters in each line. * The Maximum line length of comments in sources is 80 characters @@ -9,17 +11,77 @@ OmegaT project uses following coding style rules and coding policy. * We don't use asterisk import. You should expand all individual imports. * You are recommended to put javadoc comments for all your public methods. * We don't set method arguments "final", but you are recommended to treat it as final. + +## I18N/L10N/Bundles + * Bundle properties should be ASCII, 7bit clean. All translations should be escaped. - * It will change to be UTF-8 after OmegaT version 6.1 beta release. + - It will change to be UTF-8 after OmegaT version 6.1 beta release. + +## API design + * Stable APIs should be under "org.omegat.core" package. +* Should not remove API, otherwise, please give `@Deprecation` for old API. +* Please care for backward compatibility, please mind plugin developers. + +## Swing GUI design + +* We use a Java Swing technology for GUI parts. * GUI parts can be; - * written by hand, or - * Use NetBeans GUI builder + - written by hand, or + - Use [NetBeans GUI builder](https://netbeans.apache.org/tutorial/main/kb/docs/java/quickstart-gui/) * We don't accept other GUI builder materials; - * such as JetBrains IntelliJ GUI builder, JForm Designer, Eclipse Window builder. - * If you want, you are recommended to implement it as a plugin. + - such as JetBrains IntelliJ GUI builder, JForm Designer, Eclipse Window builder. + - If you want, you are recommended to implement it as a plugin. + +### GUI programming hints + +We encourage developers to take an approach of MVC design. + +- You can design GUI parts as View, such as `o.o.g.p.v.AppearancePreferencePanel` class. +- You can write logics as Controller, such as `o.o.g.p.v.AppearanceContoller` class. +- Sometimes a custom Model is required for complex design, such as `o.o.g.p.v.PluginInfoTableModel` + +### Labels translation + +* Please define localized labels got by `OStrings.getString` from bundle. +* For further maintenance, it is better to make UI components visibility as `package-private` + and set its label in Controller class, using a syntax like + `Mnemonics.setLocalizedText(ViewClass.uiComponentField, OString.getString("TF_LABEL_FOO"));` + +### Source code location to maintain + +* Typical UI components are defined; + + - Preference pane contents: classes under o.o.g.preferences.view package + - Dialogs: o.o.g.dialogs + - aligner: sub-project folder under aligner/src/main/java folder + - password dialog for team project: under o.o.c.team2.impl package. + +> **Warning**: +> +> When UI parts has a comment like +> ``` +> /** +> * This method is called from within the constructor to initialize the form. +> * WARNING: Do NOT modify this code. The content of this method is always +> * regenerated by the Form Editor. +> */ +> // //GEN-BEGIN:initComponents +>``` +> +> It is generated by NetBeans GUI Editor. You should use the editor to manipulate the file. +> Please find a file that has same file name but extension is ".form" + +## XML parser + * We move XML parser to be StAX based instead of JAXB because of performance. - * We use [Jackson](https://github.com/FasterXML/jackson) XML serialization library. + - We use [Jackson](https://github.com/FasterXML/jackson) XML serialization library. + +## Modules + +* We split Machine Translation service connectors, Aligner, Spell Checker driver and + dictionary drivers as sub project and build as modules. +* Modules are installed in "/modules" instead of "/plugins" ## language and characters @@ -28,8 +90,8 @@ OmegaT project uses following coding style rules and coding policy. - You should use ASCII characters and 7bit clean for variable names, method names et. al. - You are allowed to use String literals in UTF-8 encoding. - You should use Bundle for localization strings. -- You can not use Right-to-Left direction characters in comments. -- You can not use invisible characters such as non-breakable-space. +- You can not use Right-to-Left direction characters in comments and code body. +- You can not use invisible characters such as non-breakable-space and tab. - When you need invisible characters in literals, please use unicode escape. ## Lint check