Coding Standards

mtschirs

Can we get a new http://vanillaforums.org/page/StandardsAndPractices ?

Looking at library/core doesn't help much, I found a mixture of:

$_ProtectedVariable
$ProtectedVariable
$protectedVariable

$Variable
$variable

function _ProtectedMethod()
function protectedMethod()

interface NameInterface
inferface IName
interface Gdn_IName

Is https://github.com/vanilla/addons/tree/master/standards/Vanilla relevant? If yes, for which part of the codebase? I would love to see this put into the page mentioned above.

Bleistivt

http://docs.vanillaforums.com/developers/contributing/coding-standard/
This is the official documentation.

It differs quite a bit from the old standard (3-space ident + CamelCase everywhere), which is why you'll see different variable naming conventions in the codebase (indentation has been fixed recently).

mtschirs

@Bleistivt: thanks!

...but really, the number of conflicting official vanilla documentations is nearly as big as the number of coding standards found in the codebase

Bleistivt

How did you find the old page? All links to the old documentation should have been removed by now.

peregrine

@Bleistivt said:
How did you find the old page? All links to the old documentation should have been removed by now.

last time I looked at both, the old documentation even though somewhat out of date was much more robust and comprehensive than the new documentation and much easier to navigate than the new one. without having to tab down side menu wondering if you would find what you were looking for. new documentation seems a bit obfuscated. The main naviagtion page with the old documentation was far superior in my opinion.

Linc

I've 301'd the old "StandardsAndPractices" page.

The new docs are much more complete than the old page at this point. They do need a minor restyling of the side menu to include indents.

@mtschirs said:
Is https://github.com/vanilla/addons/tree/master/standards/Vanilla relevant? If yes, for which part of the codebase? I would love to see this put into the page mentioned above.

Yes, and it is on the official Coding Standards docs page, including how to use it.

mtschirs

@Bleistivt: I found it via Google search.
@Linc: Thanks
@peregrine: I agree, some old docs are still relevant and more comprehensive. Still, I couldn't bring myself to contribute to the new docs yet...

Linc

@mtschirs said:
Still, I couldn't bring myself to contribute to the new docs yet...

Mind if I ask what's making you hesitate? Onboarding folks to contributing there is of particular interest to me.

peregrine

I can tell you what others have mentioned regarding hesitation on contributing via github issues, pulls, etc or giving up on contributing.

comes down to two or three primary issues.

• minimal feedback
• lack of follow through commit and/or comment, sliding enhancements, etc. on a timely basis

• random replies (sometimes non-existent) in a random (sometimes glacial) time frame.

  you may have reasons for why the two issues occur (time and priorities). but it is still a reason why it is limited to a few people or they eventually give up because they feel like they are submitting to a black hole or void. Perhaps if someone allocated more time to feedback and commits on a regular non-random interval there would be a larger input from community. just some observations that are meant to be critically constructive rather than negative.

As for mtschirs, I am sure he will answer, but it seems apparent, he likes to be careful, conscientous, and fully understand things before he would begin documenting despite the fact that he probably understands more than 99.9% of the community in the short time he's been looking theough docs and code.

Linc

We've been much better about evaluating & replying to pull requests in a timely way this year. And I'm quite sure that "glacial" has never been an applicable term to merging docs changes. I've always been on top of that since the new docs format was created.

mtschirs

The way I understood peregrine is that due to limited or non-instant feedback to community contributions in general, the group of people who gain a deep enough understanding to be able to contribute to the docs and still feel encouraged to do so because of idealism? stays pretty small.

For my part, I was always given pretty quick feedback by Linc. But I also stumbled over some issues that seem to linger around for longtime already.

@Linc: Contributing code is very different to contributing docs. While the first has advantages for both parties, the second is pretty much advantageous for Vanillaforums Inc. only to reach out to possibly future contributors and customers. Might also have to do with the docs giving off vibes of being a big advertisment for going cloud-hosted (nothing bad with that, just doesn't make me want to dedicate my free time to it). And describing us possible contributors as 'tight-budget hobbyist tinkerers'... I exaggerate, but only a bit

Also, I noticed the "improve document" link leading to github, so visibility is not the problem. But when I look up the docs, I do so because I seek advice, not because I feel competent enough to give advice.

When I started my first plugin a few weeks ago, I downloaded a sample plugin from somewhere here that uses outdated practices (e.g. outdated coding style). Later, I looked at other plugins and noticed they handle things differently. Still, I feel that a lot of code I have seen doesn't represent the state of the art (e.g. Gdn_Form in the core) and therefore consider myself not competent enough to give advice based on what I have seen.

@peregrine: you know how to appeal to my ego

vrijvlinder

Based on your understanding thus far , I would give it a week or so before you were competent enough to give advice .

Linc

@mtschirs said:
Linc: Contributing code is very different to contributing docs. While the first has advantages for both parties, the second is pretty much advantageous for Vanillaforums Inc. only to reach out to possibly future contributors and customers.

Aren't future contributors advantageous to everyone?

@mtschirs said:
Might also have to do with the docs giving off vibes of being a big advertisment for going cloud-hosted

I think it's more to do with having ceded that messaging to the marketing department than anything. Our non-developers are perhaps over-paranoid about open source cannibalizing our sales. The docs & community repos are open source and I'm open to reconsidering the messaging.

But seriously... are we not 'tight-budget hobbyist tinkerers'?

mtschirs

@Linc schrieb:
But seriously... are we not 'tight-budget hobbyist tinkerers'?

indeed

vrijvlinder

Touche ..

R_J

I have problems with variable names. They are not really covered in the docs.
When I look at $DiscussionID it will become $discussionID, correct? Coming from this, $ID will become $iD which looks really weird. I would expect it to be $id and therefore it should be $discussionId. I know this may sound philosophical, but I really waste time on thinking about such things...

peregrine

@r_j said: I have problems with variable names. They are not really covered in the docs.

valid. There is a school of thought about coding standards.

why is there a standard -
- for ease of visually looking at code and interpreting
- to keep programming syntax smatches at a minimum due to upper and lowercase dydlexia and malaprops
- to keep philosophers busy.

It is similar to arguing about how many angels can fit on a pinhead when discussing angel flight and the development of angel wings may prove more useful. The evolution of wings in angels and natural selection for this would be interesting and the reason for small size, not to mention invisibility.

Up to a point, coding syntax can be like arranging desk chairs on the titanic when you have more important things to do with coding logic and consistency.