Zandronum Chat @ irc.zandronum.com
#zandronum
Get the latest version: 3.0
Source Code

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0003591Doomseeker[All Projects] Documentationpublic2019-01-01 20:292019-01-08 14:27
ReporterPol M 
Assigned ToWubTheCaptain 
PrioritynoneSeverityfeatureReproducibilityN/A
StatusacknowledgedResolutionopen 
PlatformLinuxOSArchOS Versionx86-64
Product Version1.2 
Target VersionFixed in Version 
Summary0003591: Programming style (for formatting tools like clang-format or astyle) is undocumented
DescriptionWith to objective to ensure that a new user (and me) uses the official format for doomseeker, we could consider using one of these tools. Also, this will allow us to define some more precise rules in formatting without implying a lot of time wasted in following formatting rules (they can easily be integrated into most IDEs). This ticket, unfortunately, would require a commit updating files.
Steps To ReproduceLook at a pull request from a new user (me). Notice that there are formatting errors. Also, I've noticed some minor style differences in different files.
Additional Information
Attached Files

- Relationships
child of 0003595confirmedWubTheCaptain Contributor documentation is not yet available 

-  Notes
User avatar (0020301)
Pol M (developer)
2019-01-03 16:47
edited on: 2019-01-06 19:09

For instance, this astyle config:

mode=c
style=allman
indent=force-tab=4
indent-cases
indent-namespaces
indent-after-parens
indent-continuation=1
min-conditional-indent=1
max-continuation-indent=80
align-pointer=type
align-reference=type

pad-oper
pad-comma
pad-header

#attach-return-type
#attach-return-type-decl

#remove-braces

meets quite closely the common style of doomseeker.

User avatar (0020302)
WubTheCaptain (developer)
2019-01-06 06:25

Related to 0003526. We need a CONTRIBUTING file or a better mention in README.
User avatar (0020303)
WubTheCaptain (developer)
2019-01-06 06:55

Now, I'm not so sure how useful documenting these rules would be without continuous integration (CI) checks. Our CI is kind of "meh" currently?

Maybe an experienced programmer can look around the source code and try to mimic the existing programming style. Or maybe the maintainer decides to accept a patch, but further contribute to fit the programming style wanted right after.

If there are "some minor style differences in different files", it's an issue we should fix; please create a new issue ticket for this for me to work on. 😊
User avatar (0020306)
Pol M (developer)
2019-01-06 10:57
edited on: 2019-01-06 10:58

Quote from Wub

Now, I'm not so sure how useful documenting these rules would be without continuous integration (CI) checks.

Since these tools automatically enforce a formatting style, there is no need to change the current CI config. A developer simply has to integrate the desired tool in their editor of choice and then make a pull request. If the said developer does not use the formatting rules, Zalewa (for instance) can run the formatting rules and see that they are not followed (no need to check for whitespace, brackets, proper indentation...). (then he would inform the developer)
Quote from Wub

Our CI is kind of "meh" currently?

There was the idea of making a clone of the repo in git and pushing it to Github to use Travis, a really good CI tool (possible ticket). For the moment it does the minimum: ensuring that broken commits in the default branch (marked with a "@") don't go unnoticed. This is good enough, but of course, it can be a lot better
Quote from Wub

Maybe an experienced programmer can look around the source code and try to mimic the existing programming style. Or maybe the maintainer decides to accept a patch, but further contribute to fit the programming style wanted right after.

This is why a formatting tool is useful: no need to worry about style any more. for instance, let's say we agree that in if/else/for cases we want a space after those words and that brackets should be in separate lines. Then if I write this:

if(!plugin.data()->demoExtensionAutomatic){}

Astyle changes the file once you save to:

if (!plugin.data()->demoExtensionAutomatic)
{
}

Quote from Wub

If there are "some minor style differences in different files", it's an issue we should fix; please create a new issue ticket for this for me to work on.

Since we don't have any rules defined yet if I were you I'd wait until we achieve some kind of resolution in this ticket before creating another one. If at the end of this ticket we achieve a file with formatting rules for one of those tools, it would be as easy as running it in all the files (except the ones that are not ours, like the "dependencies folder" and other files inside the source tree) with a simple enough command.

User avatar (0020307)
WubTheCaptain (developer)
2019-01-08 14:27

For the note, I have no preference for C++ formatting either way. (For C, it'd be OpenBSD KNR or K&R/ANSI-C.)

Issue Community Support
Only registered users can voice their support. Click here to register, or here to log in.
Supporters: Pol M
Opponents: No one explicitly opposes this issue yet.

- Issue History
Date Modified Username Field Change
2019-01-01 20:29 Pol M New Issue
2019-01-01 20:29 Pol M Status new => assigned
2019-01-01 20:29 Pol M Assigned To => Pol M
2019-01-01 20:29 Pol M Status assigned => feedback
2019-01-03 16:47 Pol M Note Added: 0020301
2019-01-03 16:47 Pol M Status feedback => assigned
2019-01-03 16:47 Pol M Assigned To Pol M =>
2019-01-03 16:47 Pol M Status assigned => feedback
2019-01-06 06:25 WubTheCaptain Note Added: 0020302
2019-01-06 06:25 WubTheCaptain Assigned To => WubTheCaptain
2019-01-06 06:25 WubTheCaptain Status feedback => confirmed
2019-01-06 06:25 WubTheCaptain Relationship added related to 0003526
2019-01-06 06:28 WubTheCaptain Status confirmed => acknowledged
2019-01-06 06:31 WubTheCaptain Category Cleanup => Documentation
2019-01-06 06:40 WubTheCaptain Summary Define an official format using a formatting tool like clang-format or astyle => Programming style (for formatting tools like clang-format or astyle) is undocumented
2019-01-06 06:43 WubTheCaptain Additional Information Updated View Revisions
2019-01-06 06:44 WubTheCaptain Additional Information Updated View Revisions
2019-01-06 06:45 WubTheCaptain Additional Information Updated View Revisions
2019-01-06 06:55 WubTheCaptain Note Added: 0020303
2019-01-06 06:59 WubTheCaptain Relationship deleted related to 0003526
2019-01-06 07:04 WubTheCaptain Relationship added child of 0003594
2019-01-06 07:26 WubTheCaptain Relationship added parent of 0003595
2019-01-06 07:27 WubTheCaptain Relationship deleted child of 0003594
2019-01-06 07:27 WubTheCaptain Relationship replaced child of 0003595
2019-01-06 07:31 WubTheCaptain Product Version => 1.2
2019-01-06 10:57 Pol M Note Added: 0020306
2019-01-06 10:58 Pol M Note Edited: 0020306 View Revisions
2019-01-06 19:09 Pol M Note Edited: 0020301 View Revisions
2019-01-08 14:27 WubTheCaptain Note Added: 0020307






Questions or other issues? Contact Us.

Links


Copyright © 2000 - 2019 MantisBT Team
Powered by Mantis Bugtracker