Styleguide

[Goombert]

This was always a huge problem when I began contributing to ENIGMA. Having to format and reformat code constantly. Recently I've taken the practice of using standard style guides for my projects and sticking to them.

I feel ENIGMA and LateralGM have suffered tremendously from the lack of an enforced styleguide. This post is not about tabs vs spaces but about using consistent formatting in both projects.

My personal preference would be the use of a mixture of space and tab indentations which I am conflicted on but have expressed in a 64Digits post:
http://www.64digits.com/users/index.php?userid=RobertBColton&cmd=comments&id=504378

I've been configuring my code editors to allow me to use a consistent coding style for multiple projects. I was simply reviewing some of ENIGMA's source code and stumbled upon the inconsistencies in formatting, caused by myself and a lot of others. You can see in the following screenshot some of the problems, some lines are indented using tabs and others with 2 or 4 spaces.



This makes it considerably difficult for contributors, including each and everyone one of us, whether we prefer tabs or spaces. The reason is simple and that is the lack of consistency. I would be able to work with either depending on what everyone else would prefer to use. But I think the quality of our code base could be seriously improved through the ratification of a standard coding style for the project with input from everyone. Please let me know what you think.

[egofree]

I feel ENIGMA and LateralGM have suffered tremendously from the lack of an enforced styleguide.

For LateralGM, IsmAvatar has defined a styleguide with an eclipse 'formatter' called 'Girard'. If i remember well, it is included in the github project. Then in eclipse, you can automatically apply this formatter on the project.

[Goombert]

Well, I'll be a monkey's uncle, you're right.
https://github.com/IsmAvatar/LateralGM/blob/master/.checkstyle

I wonder if it defaults when you open the editor or if it needs configured in Eclipse first like I had to do with the Google styleguide I needed for my other library. If it is the case of the former then that leads me to point out that I don't particularly like this style and I don't think Josh or anyone but IsmAvatar does, but I believe this has been mentioned before. In practice I would rather just keep it what it is then try to change it. However I do feel ENIGMA and LateralGM would benefit further if they used the same styleguide.

Regarding ENIGMA, since Josh works at Google, and the compiler has always been written with that style, I feel as though that's the one we should go with, at least for ENIGMA. The reason being is that Google has the styleguide well defined and you can even download an XML schema file for it to plug into Eclipse or other editors.

Still looking to see what everyone else thinks as I wouldn't want to make contribution difficult for everyone, I think this would actually make it easier and it's bugging me to the point I may check out the latest ENIGMA and clean it up if we can all decide. I am looking basically to get everyone's approval to enforce it since it seems egofree is comfortable with it, I am comfortable with it, and so is Josh. Using style formatters is not difficult but my only wish is that Josh would have sat me down and made me think about it before letting me contribute instead of just letting me ignore it. Anyway, most projects adhere to a styleguide at least to some degree, but ENIGMA straight up has nothing to the point the code is a complete mess, at the very least we need to define the indentation style.

[TheExDeus]

I remember reading Google's styleguide and I don't remember seeing something I really disliked. I have heard a lot of criticism for it though. On one of my projects I actually started making my own styleguide based on the one here: http://www.openvdb.org/documentation/doxygen/codingStyle.html - it is short and I also agree with about 90% of the stuff in it.

Tabs/Space wise I previously used Tabs. Then about 2 years ago Josh and others here asked me to switch to spaces as we develop on different editors and different OS's. This meant that tabs and spaces didn't go together that well and tabs created squished or stretched code. So we decided that a tab should be 2 spaces and I have been coding like that since. I have actually replaced most tabs with 2 spaces in a lot of ENIGMA code now. As yourself mentioned - both of them have advantages and disadvantages. The advantage of having tabs easy to replace is also not that great considering line indentation in 99% of cases are at the beginning of a line. This means that you can regex spaces however you want without touching other spaces in the code.

I use Sublime Test3 now as an editor and I really enjoy. I have configured it to use 2 spaces for tabs. That Elastic Tabstops idea is not bad either, but it is something to be getting used to. Maybe if I actually saw the table rows (like in the colored gif in the website here: http://nickgravgaard.com/elastic-tabstops/columnblocks_coloured.gif) it would be easier for me to use.

edit: What I actually want is a way to annotate large pieces of code in a better way. I know that having a file with hundreds of lines is usually not considered pretty, but sometimes things like that happen. And in a 500 line .cpp file I would want a way to show large titles.
For example for a code section like this:

Or just larger titles like this:

Of course you can always search for the part you want, but that doesn't really work if the code base is large or if you aren't the one who wrote it. Sublime has cool fuzzy searching, but even with that it is sometimes hard to find the part you want. So I end up scrolling trough code (or the code map on the size) and in these cases large titles would really help to find the part I'm looking for.

[Goombert]

Alright, great thanks for the feedback some other things to consider:

I like the solution I mentioned above regarding tabs when tabs are used for normal indent and vertical tabs are used to create the columnar alignment, this makes it work with python.


In that picture it would mean "string s" whitespace would be replaced with a single preceding vertical tab, and all of the other lines would continue to be normal tabs.

Regarding Sublime, I haven't switched to it yet, but there is an elastic tabstops plugin for it:
https://github.com/SublimeText/ElasticTabstops

I also got this FF extension which stops making the tab key change focus so it works nicely with pastie.org, even though pastebin.com already had tab input support (depends on the website and how keen the developers are, stack overflow is a pain to format code)
https://addons.mozilla.org/en-us/firefox/addon/tabinta/

Whether you use spaces or not though tab is still used for the indent so you can select multiple lines, code editing in browsers sucks either way you go imo.

Anyway I've personally gone 180 degrees back the other way I think to just tabs because I feel all of the advantages outweigh the benefits when properly configured and because of my above discoveries and that tabs separate model from view.

Anyway, not to be rude Harri, but to be honest, I don't want to do our own styleguide. Whether anybody likes Google's or not I don't really care, it's very popular and I feel just as comfortable working with it. So my vote goes towards us adopting the Google styleguide to make things easier for new contributors and because it is already widely adopted and has a number of extensions for many editors, plus it's what Josh and I already have configured on our computers and you do partially as well.

I'll wait and see what he says, if we get his seal of approval I'm checking out ENIGMA's latest branch and running over the whole code base with a formatter. Maybe though since you don't mind the elastic tabstops idea we could be a revolutionary project in using this coding convention and make it more popular, let's see what Josh has to say and egofree or anybody else feel free to weigh in too.

Edit: Also I love your idea about the code headers, definitely agree with you there. I also get kind of sleepy reading code with doxygen as well, this is why I like a class hierarchy view.

[egofree]

I use Sublime Test3 now as an editor and I really enjoy.

This is a little bit off-topic, but since you are talking about text editor, there is a totally free and open-source alternative, which is is fine also : atom editor (https://atom.io/).  It has also tons of plugins available. (To install new ones : File->settings->packages).

[TheExDeus]

Anyway, not to be rude Harri, but to be honest, I don't want to do our own styleguide. Whether anybody likes Google's or not I don't really care, it's very popular and I feel just as comfortable working with it. So my vote goes towards us adopting the Google styleguide to make things easier for new contributors and because it is already widely adopted and has a number of extensions for many editors, plus it's what Josh and I already have configured on our computers and you do partially as well.

I didn't propose we make our own styleguide. I just mentioned that I adopted and changed one myself, because I wanted something that covers 99% of the code cases and can be printed on one page. The google guide is a book and touches a lot of things (many of which have been challenged over the years). I agree with "formatting" part but not with the more technical parts. As I think you probably want to adopt the formatting then I have no issues with that.

I'll wait and see what he says, if we get his seal of approval I'm checking out ENIGMA's latest branch and running over the whole code base with a formatter. Maybe though since you don't mind the elastic tabstops idea we could be a revolutionary project in using this coding convention and make it more popular, let's see what Josh has to say and egofree or anybody else feel free to weigh in too.

Maybe I can merge my branch then. Or you checkout it, because it has a lot of changes.

Edit: Also I love your idea about the code headers, definitely agree with you there. I also get kind of sleepy reading code with doxygen as well, this is why I like a class hierarchy view.

Sadly I haven't found an editor which would allow me to implement something like that in a plugin. Maybe egofree's mentioned Atom could do it as it basically renders html. Neither Code::Blocks, Notepad++ or Sublime allows me to do something like that. At least as far as I checked.

This is a little bit off-topic, but since you are talking about text editor, there is a totally free and open-source alternative, which is is fine also : atom editor (https://atom.io/).  It has also tons of plugins available. (To install new ones : File->settings->packages).

That does look interesting. It seems C++ is mostly an afterthought for it, but so it was for Sublime, so I can probably configure it so it works for me. I will check it out.

[Goombert]

Actually Harri, Josh already took the liberty of writing this all down, so you know what guys, let's table this discussion.
http://enigma-dev.org/docs/Wiki/Coding_conventions

Here's what we are going to do:
* Link this page from the main wiki page under the contributions section (I already have).
http://enigma-dev.org/docs/Wiki/Main_Page
* Try to persuade new contributors to follow these conventions and guide them if they need assistance in configuring their code editor.
* Do not over trivialize a pull request where the formatting is incorrect, just mention it as a side note, pull it and fix the formatting yourself so they know for a future patch submission. This way they will not be discouraged by the rejection of their first commit.
* The coding conventions can be followed loosely, just don't let it get out of hand.
* Continue to correct areas where the formatting is wrong. This includes a lot of places I may have touched because nobody ever really explained the coding conventions or why they are important to me.

Do not go crazy trying to run a formatter over everything like I suggested I was going to do, this problem has been enough of a distraction already from bigger things that need solved. Harri also mentioned that he's already fixed a number of formatting problems. Just please follow this advice as we continue into the future.

I didn't propose we make our own styleguide

I know, the reason I said that was because I didn't want you to get distracted, there's more important things, I just wanted your input.

Maybe I can merge my branch then. Or you checkout it, because it has a lot of changes.

That would be nice, when I have time I am going to run the formatter over LGM because it has gotten way out of hand and I let it get that way. Nobodies been in there to do some cleaning and now that I know how I am going to do that. But also I was going to address the issues you and egofree were having and fix any of the remaining JoshEdit problems cleanly if there are any. So it would be nice if you have whatever changes you've made into ENIGMA master so I can get a working copy set up and fix these other issues by like Sunday.

Maybe egofree's mentioned Atom could do it as it basically renders html.

I would use the feature if any editor ever added it. Egofree's suggestion would probably be the best because look at how Eclipse parses HTML and Javadoc's to provide documentation in the IDE from the source code (this was something we did want to do with LGM). An editor that can do that is the best place to implement what you want.

This is a little bit off-topic, but since you are talking about text editor, there is a totally free and open-source alternative, which is is fine also : atom editor (https://atom.io/).  It has also tons of plugins available. (To install new ones : File->settings->packages).

Also, DaSpirit had me try Atom and iirc it didn't work very well and it was very laggy I believe because it's written in JavaScript. Don't take my word for it though examine the program for yourself. I really liked Sublime when I just tested it and its package management, but I recommend you support free and open source software over proprietary software such as Sublime.