Recent changes to Coding_Standards

Coding_Standards modified by Vidar Hasfjord

Vidar Hasfjord — Mon, 11 Aug 2025 16:03:49 -0000

--- v79
+++ v80
@@ -169,7 +169,7 @@

 * **NEW**: When describing new features, refer to the ticket in the request tracker, if any, using the format "\[feature-requests:#123\]". _Rationale_: A reference adds helpful context and allows version control systems to generate a link automatically.
 * **CHG**: This tag will apply to most changes that are not new features nor bug fixes. Add context and references, if applicable.
-* **BUG**: Describe the bug as it was, i.e. copy the ticket title from the bug tracker, and append a ticket reference using the format "\[bugs:#123\]". If the bug is not in the tracker, but it is known that the bug was introduced by a change in a specific revision, i.e. the issue is a regression, then add a reference to the guilty revision using the format "\[r0000\]". If neither applies, then be as specific as possible about the nature of the issue. Then, if it is not obvious, add a description of the resolution of the issue.
+* **BUG**: Copy the ticket title from the bug tracker, and append a ticket reference using the format "\[bugs:#123\]". If the bug does not have a ticket, provide a good description of the bug and include any relevant references (revision, discussion, etc.). Then, if it is not obvious, add a description of the resolution of the issue.
 * **RGR**: This tag applies to regressions; issues that appear due to code changes, e.g. the build failing. Use this tag rather than BUG when you want to point out that the code used to work just fine and that a particular change broke it. Reference the guilty revision using the format "\[r0000\]", and then state the resolution of the issue.

 *Exception*: Changes entirely related to version control can omit the tags, e.g. "Added svn:mergeinfo".

Coding_Standards modified by Vidar Hasfjord

Vidar Hasfjord — Mon, 11 Aug 2025 14:25:45 -0000

--- v78
+++ v79
@@ -165,30 +165,38 @@

 *Rationale*: The log message should provide helpful information at a glance about what has changed in the revision, even to a novice unfamiliar with the project.

-Use one of the following tags to prefix the description of each change; for example: 
-
-> String enhancements for the TFoo class:
-> 
-> NEW: Added an owl::tstring overload to TFoo::GetString \[feature-requests:#123\].
-> CHG: Elaborated on the documentation of TFoo::GetString.
-> BUG: TFoo::GetString causes buffer overrun \[bugs:#456\]. Resolution: Added buffer check.
-> RGR: UNICODE build fails \[r789\]. Resolution: Wrapped strings in \_T macros.
-> 
-> TODO: Investigate the purpose of TFoo::Contrived; seems not needed anymore.
-
-If the submission consists of several changes, as above, then add a header that describes the overall purpose or context for the changes. If you cannot provide a good header, it is probably an indication that the submission bundles unrelated changes, and you should split it up into smaller orthogonal submissions. 
-
-* **NEW**: When describing new features, refer to the ticket in the request tracker, if any, using the format "\[feature-requests:#123\]". _Rationale_: This allows version control systems to link the revision with the issue tracker automatically.
-* **CHG**: This tag will apply to most changes that are not new features nor bug fixes. Since this tag rarely refers to the tracker, it is especially important that the log message is helpful and complete. Don't save space!
-* **BUG**: Note that this tag is short for "I implemented a bug-fix for the following issue", so "BUG: Fixed the buffer overflow in Foo" is redundant. Simply use "BUG: Buffer overflow in Foo" instead. Describe the bug as it was, i.e. copy the ticket title from the bug tracker, and append a ticket reference using the format "\[bugs:#123\]". If the bug is not in the tracker, but it is known that the bug was introduced by a change in a specific revision, i.e. the issue is a regression, then add a reference to the guilty revision as shown in the example above. If neither applies, then be as specific as possible about the nature of the issue. Then, if it is not obvious, add a description of the resolution as shown in the example above.
-* **RGR**: This tag applies to regressions; issues that appear due to code changes, e.g. the build failing. Use this tag rather than BUG when you want to point out that the code used to work just fine and that a particular change broke it. In the log statement, refer to the change that caused the regression, with a reference to the revision number, and then state the resolution of the issue.
-
-Feel free to add comments and todo-items at the end of the log message. This may help other developers review and further improve the code. 
-
-*Exception*: Changes entirely related to version control can omit the tags. 
+Use one of the following tags to prefix the description of each change: 
+
+* **NEW**: When describing new features, refer to the ticket in the request tracker, if any, using the format "\[feature-requests:#123\]". _Rationale_: A reference adds helpful context and allows version control systems to generate a link automatically.
+* **CHG**: This tag will apply to most changes that are not new features nor bug fixes. Add context and references, if applicable.
+* **BUG**: Describe the bug as it was, i.e. copy the ticket title from the bug tracker, and append a ticket reference using the format "\[bugs:#123\]". If the bug is not in the tracker, but it is known that the bug was introduced by a change in a specific revision, i.e. the issue is a regression, then add a reference to the guilty revision using the format "\[r0000\]". If neither applies, then be as specific as possible about the nature of the issue. Then, if it is not obvious, add a description of the resolution of the issue.
+* **RGR**: This tag applies to regressions; issues that appear due to code changes, e.g. the build failing. Use this tag rather than BUG when you want to point out that the code used to work just fine and that a particular change broke it. Reference the guilty revision using the format "\[r0000\]", and then state the resolution of the issue.
+
+*Exception*: Changes entirely related to version control can omit the tags, e.g. "Added svn:mergeinfo".
+
+*Note*: If a message does not refer to a ticket, revision or discussion, it is especially important that the log message is helpful and complete. Don't save space!
+
+*Note*: The BUG and RGR tags are shorthand for "bug fix" and "regression fix", respectively, so "BUG: Fixed the buffer overflow in Foo" is redundant. Simply use "BUG: Buffer overflow in Foo" instead.
+
+*Tip*: If the submission consists of several changes, then add a header that describes the overall purpose or context for the changes. If you cannot provide a good header, it is probably an indication that the submission bundles unrelated changes, and you should split it up into smaller orthogonal submissions. 
+
+*Tip*: Feel free to add comments and todo-items at the end of the log message. This may help other developers review and further improve the code. 

 *Tip*: Log messages can be edited, so review, correct and improve log messages as you see fit. 

+Example:
+
+~~~text
+String enhancements for the TFoo class:
+
+NEW: Added an owl::tstring overload to TFoo::GetString [feature-requests:#123].
+CHG: Elaborated on the documentation of TFoo::GetString.
+BUG: TFoo::GetString causes buffer overrun [bugs:#456]. Resolution: Added buffer check.
+RGR: UNICODE build fails [r789]. Resolution: Wrapped strings in _T macros.
+
+TODO: Investigate the purpose of TFoo::Contrived; seems not needed anymore.
+~~~
+
 

 ### Commit to the trunk

@@ -201,19 +209,22 @@
 

 ### Use the Subversion Merge Tracking feature

-Subversion provides [merge tracking](http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-merge.html#tsvn-dug-merge-tracking) functionality that records which revisions have been merged from one branch to another. This information is recorded in the svn:mergeinfo property. You should normally always use the merge functions to keep this information correct and up-to-date. If you manually merge changes, or want to exclude a revision from being merged, you need to manually update svn:mergeinfo accordingly. _Rationale_: The merge feature automates and simplifies merging. 
-
-When committing a merge to the repository, provide a log message starting with "Merged \[r*REVNUM*\] from *path* to *path*:", then followed by a copy of the log messages from the revisions merged. For example: 
-
-> Merged \[r1001\] from trunk to branches/6.44:
-> 
-> NEW: Added blah blah blah.
-> CHG: Changed blah blah blah.
-> BUG: Blah blah blah is nonsense.
-
-Feel free to abbreviate long messages. The point is to get an overview of the changes merged, including links to related revisions and tickets. E.g. if the source revision has a lot of changes, you can provide a summary instead.
-
-_Rationale_: A complete log message makes browsing the repository log easier, and makes it possible to recreate the merge history, should the svn:mergeinfo property be corrupted. 
+Subversion provides [merge tracking](http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-merge.html#tsvn-dug-merge-tracking) functionality that records which revisions have been merged from one branch to another. This information is recorded in the svn:mergeinfo property. You should normally always use the merge functions to keep this information correct and up-to-date. If you manually merge changes, or want to exclude a revision from being merged, you need to manually update svn:mergeinfo accordingly.
+
+When committing a merge to the repository, provide a log message starting with "Merged \[r*REVNUM*\] from *path* to *path*:", then followed by a copy of the log messages from the revisions merged, separated by dashed lines.
+
+*Rationale*: The merge feature automates and simplifies merging. A complete message makes browsing the log easier, and makes it possible to recreate the merge history, should the svn:mergeinfo property be corrupted. 
+
+*Tip*: Feel free to abbreviate long messages. The point is to get an overview of the changes merged, including links to related revisions and tickets. If the source revision has a lot of changes, you can provide a summary instead.
+
+Example: 
+
+~~~text
+Merged [r1001] and [r1002] from trunk to branches/6.44:
+NEW: Blah blah blah [feature-requests:#123].
+---
+RGR: Blah blah broke blah [r1001].
+~~~

 

 ### Merge often

Coding_Standards modified by Vidar Hasfjord

Vidar Hasfjord — Mon, 11 Aug 2025 13:34:21 -0000

--- v77
+++ v78
@@ -129,6 +129,10 @@
 - A mechanical, consistent update across a subsystem (e.g. changing coding style conventions).
 - Documentation and naming consistency updates confined to one component or area.

+*Tip*: Use a descriptive header line with context (e.g. branch, subsystem, component, class, function) and a link to the relevant ticket, revision or discussion, if applicable. Then follow with a concise explanation that clarifies what changed and why.
+
+*Exception*: Do not over-aggregate. If a set of edits only appears related but may need to be reverted or merged independently later, keep them in separate revisions.
+
 Example [r7852]:

 ~~~text
@@ -153,10 +157,6 @@
 CHG: TFrameWindow::RestoreMenu: Optimised move-semantics; the menu descriptor is now
 moved into the SetMenu parameter.
 ~~~
-
-*Tip*: Use a descriptive header line with context (e.g. branch, subsystem, component, class, function) and a link to the relevant ticket, revision or discussion, if applicable. Then follow with a concise explanation that clarifies what changed and why.
-
-*Exception*: Do not over-aggregate. If a set of edits only appears related but may need to be reverted or merged independently later, keep them in separate revisions.

 

 ### Provide helpful and complete log messages with tags

Coding_Standards modified by Vidar Hasfjord

Vidar Hasfjord — Mon, 11 Aug 2025 13:26:26 -0000

--- v76
+++ v77
@@ -169,10 +169,10 @@

 > String enhancements for the TFoo class:
 > 
-> NEW: Added an owl_string overload to TFoo::GetString \[feature-requests:#123\].
+> NEW: Added an owl::tstring overload to TFoo::GetString \[feature-requests:#123\].
 > CHG: Elaborated on the documentation of TFoo::GetString.
 > BUG: TFoo::GetString causes buffer overrun \[bugs:#456\]. Resolution: Added buffer check.
-> RGR: Build fails after use of std::optional in "dc.h" \[r5016\]. Resolution: Included "gdiobjec.h" to complete types.
+> RGR: UNICODE build fails \[r789\]. Resolution: Wrapped strings in \_T macros.
 > 
 > TODO: Investigate the purpose of TFoo::Contrived; seems not needed anymore.

Coding_Standards modified by Vidar Hasfjord

Vidar Hasfjord — Mon, 11 Aug 2025 13:19:50 -0000

--- v75
+++ v76
@@ -172,8 +172,7 @@
 > NEW: Added an owl_string overload to TFoo::GetString \[feature-requests:#123\].
 > CHG: Elaborated on the documentation of TFoo::GetString.
 > BUG: TFoo::GetString causes buffer overrun \[bugs:#456\]. Resolution: Added buffer check.
-> BUG: TFoo::Send fails for Unicode (regression in \[r789\]). Resolution: Wrapped strings in the \_T macro.
-> RGR: Build fails after use of std::optional in "dc.h" \[r5016\]. Resolution: Included "gdiobjec.h" (complete types).
+> RGR: Build fails after use of std::optional in "dc.h" \[r5016\]. Resolution: Included "gdiobjec.h" to complete types.
 > 
 > TODO: Investigate the purpose of TFoo::Contrived; seems not needed anymore.

Coding_Standards modified by Vidar Hasfjord

Vidar Hasfjord — Mon, 11 Aug 2025 12:46:16 -0000

--- v74
+++ v75
@@ -154,9 +154,9 @@
 moved into the SetMenu parameter.
 ~~~

-*Tip*: Use a descriptive header line with context (e.g. branch, subsystem, component, class, function) and a link to the relevant ticket/revision/discussion, if applicable), then follow with a concise explanation that clarifies what changed and why.
-
-*Tip*: Do not over-aggregate. If a set of edits only appears related but may need to be reverted or merged independently later, keep them in separate revisions.
+*Tip*: Use a descriptive header line with context (e.g. branch, subsystem, component, class, function) and a link to the relevant ticket, revision or discussion, if applicable. Then follow with a concise explanation that clarifies what changed and why.
+
+*Exception*: Do not over-aggregate. If a set of edits only appears related but may need to be reverted or merged independently later, keep them in separate revisions.

 

 ### Provide helpful and complete log messages with tags

Coding_Standards modified by Vidar Hasfjord

Vidar Hasfjord — Sun, 10 Aug 2025 21:58:11 -0000

--- v73
+++ v74
@@ -156,7 +156,7 @@

 *Tip*: Use a descriptive header line with context (e.g. branch, subsystem, component, class, function) and a link to the relevant ticket/revision/discussion, if applicable), then follow with a concise explanation that clarifies what changed and why.

-*Tip*: Do not over-aggregate. If a set of edits only appears related but may need to be reverted independently later, keep them in separate revisions.
+*Tip*: Do not over-aggregate. If a set of edits only appears related but may need to be reverted or merged independently later, keep them in separate revisions.

 

 ### Provide helpful and complete log messages with tags

Coding_Standards modified by Vidar Hasfjord

Vidar Hasfjord — Sun, 10 Aug 2025 19:32:00 -0000

--- v72
+++ v73
@@ -161,7 +161,9 @@
 

 ### Provide helpful and complete log messages with tags

-Never submit empty log messages to the code repository. Provide a helpful and complete log message detailing your changes. Prefer full sentences, and always end the message with a period/full stop. This makes it clear that the message has not been truncated.
+Never submit empty log messages to the code repository. Provide a helpful and complete log message detailing your changes. Always include context in the message (branch, subsystem, class, function, ticket reference). Prefer conventional professional writing style (full sentences, captialisation, punctuation), and avoid programmer speak and shorthand.
+
+*Rationale*: The log message should provide helpful information at a glance about what has changed in the revision, even to a novice unfamiliar with the project.

 Use one of the following tags to prefix the description of each change; for example: 

@@ -184,16 +186,16 @@

 Feel free to add comments and todo-items at the end of the log message. This may help other developers review and further improve the code. 

-_Exception_: Changes entirely related to version control can omit the tags. 
-
-_Tip_: Log messages can be edited, so review, correct and improve log messages as you see fit. 
+*Exception*: Changes entirely related to version control can omit the tags. 
+
+*Tip*: Log messages can be edited, so review, correct and improve log messages as you see fit. 

 

 ### Commit to the trunk

 Cutting edge development happens on the trunk of the repository, and normally revisions are committed there. Revisions to release branches need more care and should usually be handled by, or cleared by, the *release manager* assigned by the project administrators. Consider committing the revision to the trunk or submitting a patch instead.

-_Rationale_: Release branches need to be carefully handled to provide stable releases to end users.
+*Rationale*: Release branches need to be carefully handled to provide stable releases to end users.

 If you cannot work on the trunk, e.g. you work on a patch for a specific release, then create a *development branch* as a copy of the specific release branch, and then commit your work on the development branch. When work has completed, the release manager will eventually merge the development branch back into the release branch (for a patch) or create a new release branch (for a major/minor version bump) in preparation for release.

Coding_Standards modified by Vidar Hasfjord

Vidar Hasfjord — Sun, 10 Aug 2025 19:14:02 -0000

--- v71
+++ v72
@@ -116,6 +116,49 @@
 Tip for TortoiseSVN users: Always thoroughly inspect your changes in TortoiseMerge before you commit, e.g. using the command "Compare with base" in the Commit dialog, or more safely, using the commands "SVN Diff" and "SVN Check for modifications" from Windows Explorer. If you spot unintended changes, you can undo them directly in the viewer (commands "Use other text block" etc. are helpful for this purpose). If you spot unrelated changes that you want to commit separately, then you can temporarily undo them in the Commit dialog by using the "Restore after commit" command. Then undo these changes in TortoiseMerge before you commit. After the commit, TortoiseSVN will restore the file so that you can commit the unrelated changes separately, if appropriate. Alternatively, use the Shelve command to create a checkpoint of your changes, then revert unrelated changes in TortoiseMerge before you commit. Afterward, you can restore your checkpoint using the Unshelve command and continue your work (or commit another change in the checkpoint).

 

+### Keep related changes together
+
+While it is important to keep unrelated changes apart, it is also very helpful to group *closely related* changes into a single revision. If several edits are part of the same logical improvement, collect them under one cohesive commit with a clear, descriptive message.
+
+*Rationale*: Grouping related changes improves the readability, overview and traceability of the history, while reducing noise and message flooding, which can clutter the log and make it less helpful. Grouping makes it easier to search the log and understand the scope of a change without piecing together multiple micro-commits.
+
+Typical candidates for grouping:
+
+- Changes related to a bug or feature-request ticket (link to the ticket in the message).
+- A cohesive refactor (overhaul) where multiple files/functions change to support one improvement.
+- A mechanical, consistent update across a subsystem (e.g. changing coding style conventions).
+- Documentation and naming consistency updates confined to one component or area.
+
+Example [r7852]:
+
+~~~text
+CHG: TWindow::SetMenu now takes ownership [feature-requests:#262].
+
+On success, the old menu is immediately destroyed, and its bitmaps, if any, are deleted.
+
+Collateral changes:
+
+NEW: SetMenu(TMenu) overload, for convenient move-semantics. If an rvalue argument is
+passed (e.g. a temporary or by explicit use of std::move), ownership is taken of the
+argument, whether or not the call succeeds or not, ensuring clean-up in all cases.
+
+CHG: TFrameWindow::AssignMenu: Optimised move-semantics; the menu or menu descriptor is
+now moved into the SetMenu parameter.
+
+CHG: TFrameWindow::MakeMenuOrId: Eliminated copy by handle release instead.
+
+CHG: TFrameWindow::MergeMenu: Optimised move-semantics; the menu descriptor is now moved
+into the first Merge parameter, and the result is moved into the SetMenu parameter.
+
+CHG: TFrameWindow::RestoreMenu: Optimised move-semantics; the menu descriptor is now
+moved into the SetMenu parameter.
+~~~
+
+*Tip*: Use a descriptive header line with context (e.g. branch, subsystem, component, class, function) and a link to the relevant ticket/revision/discussion, if applicable), then follow with a concise explanation that clarifies what changed and why.
+
+*Tip*: Do not over-aggregate. If a set of edits only appears related but may need to be reverted independently later, keep them in separate revisions.
+
+

 ### Provide helpful and complete log messages with tags

 Never submit empty log messages to the code repository. Provide a helpful and complete log message detailing your changes. Prefer full sentences, and always end the message with a period/full stop. This makes it clear that the message has not been truncated.

Coding_Standards modified by Vidar Hasfjord

Vidar Hasfjord — Fri, 25 Jul 2025 13:10:58 -0000

--- v70
+++ v71
@@ -113,7 +113,7 @@

 Note that this recommendation even applies to seemingly small changes of the formatting or style of surrounding code. For changes related to formatting and style it is recommended to store these up for larger coordinated changes. _Tip_: Keep a record of such proposed changes and coordinate with the other developers for a major overhaul of the code.

-Tip for TortoiseSVN users: Always thoroughly inspect your changes in TortoiseMerge before you commit, e.g. using the command "Compare with base" in the Commit dialog, or more safely, using the commands "SVN Diff" and "SVN Check for modifications" from Windows Explorer. If you spot unintended changes, you can undo them directly in the viewer (commands "Use other text block" etc. are helpful for this purpose). If you spot unrelated changes that you want to commit separately, then you can temporarily undo them in the Commit dialog by using the "Restore after commit" command. Then undo these changes in TortoiseMerge before you commit. After the commit, TortoiseSVN will restore the file so that you can commit the unrelated changes separately, if appropriate.
+Tip for TortoiseSVN users: Always thoroughly inspect your changes in TortoiseMerge before you commit, e.g. using the command "Compare with base" in the Commit dialog, or more safely, using the commands "SVN Diff" and "SVN Check for modifications" from Windows Explorer. If you spot unintended changes, you can undo them directly in the viewer (commands "Use other text block" etc. are helpful for this purpose). If you spot unrelated changes that you want to commit separately, then you can temporarily undo them in the Commit dialog by using the "Restore after commit" command. Then undo these changes in TortoiseMerge before you commit. After the commit, TortoiseSVN will restore the file so that you can commit the unrelated changes separately, if appropriate. Alternatively, use the Shelve command to create a checkpoint of your changes, then revert unrelated changes in TortoiseMerge before you commit. Afterward, you can restore your checkpoint using the Unshelve command and continue your work (or commit another change in the checkpoint).

 

 ### Provide helpful and complete log messages with tags