[Repo] Comment Headers

[Nestharus]

Just a set of nice looking headers and etc that were developed over a long period of time. I typically just cnp'd these out of existing scripts I wrote, so I thought a template would be nicer =).

If anyone else has any other comment styles they'd like to share, please reply with them and I'll link them in the first post. Also feel free to help improve comment headers ;D.

I'm submitting this because a lot of people struggle with headers. There are many styles from simple ones to more complex ones. This is one that I found to be pretty good for vjass resources.

Just cnp wherever you need and change the stuff to w/e. In lib header, categories you don't need can be removed (not all libraries have a settings area or functions or structs) and others can be added (more modules, structs, etc). Same goes for struct header (not all structs have fields or methods or w/e).

The order I went in was operators, fields, then methods. Of methods, I do constructor/destructor first, then rest of methods.

I hope this helps everyone organize their code more =).

Comment Header Styles

• nestharus' Comment Headers

 

[Nestharus]

gone

 

[Bribe]

Why is this in the JASS scripts submissions? Shouldn't this be a Tutorial? I can move it there if so.

 

[Nestharus]

It shouldn't be a tut. Not sure where to put it actually ;P.

 

[chobibo]

These are header templates, so I guess it should be here in scripts.

 

[Bribe]

Yeap, this is a good repository. It is also welcome to grow if any more artistic development comes across. I've removed your signature.

 

[Magtheridon96]

What about Jesus4Lyf's Documentation Style?
It's awesome and that's exactly how I'm going to submit every one of my resources in this section as of now

 

[Nestharus]

I can't even read his document style ;o. It's way too much text ^)^.

 

[Nestharus]

Just came up with this excellent commenting style while doing some Lua

JASS version (/* */ around)

Ability = {}
/*-----------------------------------------------------------------------------------------------
*
*   Fields
*   ---------------------------------------------------------------------------------------------
*   *   ->  enabled         |   is enabled
*   *   ->  maxpower        |   maximum power of ability (in base 2)
*   *   ->  isperc          |   is percent
*   *   ->  abilityid       |   id of ability object
*   *   ->  field           |   id of ability field that gives data bonus
*   *   ->  name            |   name to assign to ability object
*   *   ->  ranged          |   the ability has a definite range
*   ---------------------------------------------------------------------------------------------
*
*   Functions
*   ---------------------------------------------------------------------------------------------
*   *
*   *   ->  function Ability.new(perc, abilityid, bonusfield, name, ranged, enabled)
*   *       -------------------------------------------------------------------------------------
*   *       *
*   *       *   Description
*   *       *   ---------------------------------------------------------------------------------
*   *       *   *
*   *       *   *   Generates a new Ability object
*   *       *   *
*   *       *   ---------------------------------------------------------------------------------
*   *       *
*   *       *   Arguments
*   *       *   ---------------------------------------------------------------------------------
*   *       *   *   -> perc                 |   is ability value percent?
*   *       *   *   -> abilityid            |   base ability id 
*   *       *   *   -> bonusfield           |   field with value of ability
*   *       *   *   -> name                 |   name of ability
*   *       *   *   -> ranged               |   does ability have defined range
*   *       *   *   -> enabled              |   is ability enabled
*   *       *   ---------------------------------------------------------------------------------
*   *       *
*   *       -------------------------------------------------------------------------------------
*   *
*   ---------------------------------------------------------------------------------------------
*
-----------------------------------------------------------------------------------------------*/

In Lua

Ability = {}
--[[---------------------------------------------------------------------------------------------
*
*   Fields
*   ---------------------------------------------------------------------------------------------
*   *   ->  enabled         |   is enabled
*   *   ->  maxpower        |   maximum power of ability (in base 2)
*   *   ->  isperc          |   is percent
*   *   ->  abilityid       |   id of ability object
*   *   ->  field           |   id of ability field that gives data bonus
*   *   ->  name            |   name to assign to ability object
*   *   ->  ranged          |   the ability has a definite range
*   ---------------------------------------------------------------------------------------------
*
*   Functions
*   ---------------------------------------------------------------------------------------------
*   *
*   *   ->  function Ability.new(perc, abilityid, bonusfield, name, ranged, enabled)
*   *       -------------------------------------------------------------------------------------
*   *       *
*   *       *   Description
*   *       *   ---------------------------------------------------------------------------------
*   *       *   *
*   *       *   *   Generates a new Ability object
*   *       *   *
*   *       *   ---------------------------------------------------------------------------------
*   *       *
*   *       *   Arguments
*   *       *   ---------------------------------------------------------------------------------
*   *       *   *   -> perc                 |   is ability value percent?
*   *       *   *   -> abilityid            |   base ability id 
*   *       *   *   -> bonusfield           |   field with value of ability
*   *       *   *   -> name                 |   name of ability
*   *       *   *   -> ranged               |   does ability have defined range
*   *       *   *   -> enabled              |   is ability enabled
*   *       *   ---------------------------------------------------------------------------------
*   *       *
*   *       -------------------------------------------------------------------------------------
*   *
*   ---------------------------------------------------------------------------------------------
*
-----------------------------------------------------------------------------------------------]]

 

[Bribe]

Opening thread.

 

[Nestharus]

Updated comment styles to improve readability and pleasantness to eyes w/o being overbearing ;p.

Too much = hard to find information you are looking for. Too little = messy.


The new styles call for absolutely no // comments. Furthermore, they call for good spacing in the required resources list as well as dashes under each title.

The boxes like the one below are now only used for grouping. You don't have mini boxes anymore for comments.

/*********************
*
*********************/

All regular comments are

/*
*
*/

These standards have proven to give very readable code. I haven't been personally using the method and struct headers because I've been too lazy to do so ; ), lol.


The // comments should now only be used for commenting out code, not for descriptions ; ). They just look fugly, lol.

 

[Bribe]

Beauty is in the eye of the beholder. Certain comments just takes some getting used to. I will never made a requirement that makes comments have to be block comments or line comments exclusively. That is stupid and you know it.

 

[Nestharus]

I suppose. The style I've been working on is just a lot easier for me to personally read than any style that involves lots of text or using // : ). For example, I couldn't read your docs in MissileRecycler because of the globs of text, heh. I couldn't even find the API D:.


I haven't had any complaints on having a hard time reading this style so far, so it must be good. It was influenced from a lot of things and a lot of people ;o.


Anyways, each person has their own style. People should pick whatever they think is the easiest to read. This style is just what I think happens to be the easiest to read while providing all relevant information ; p. Really, I'm also tempted to say that any credits belong in the post, not in the resource, but I've been putting credits into headers anyways, so ;\.

If you want to put up your own style, go for it and I'll link to it : ).

 

[Magtheridon96]

I like:

/*
*
*/

I started using them over a week ago and they're increasing readability by a ton.

 

[Magtheridon96]

All in favor of sticking this, say Aye.

Aye.

 

[gorillabull]

Aye!!

 

[Elprede]

Aye.

 

[Magtheridon96]

2 more votes and I'll stick this.

 

[Anachron]

Honestly I don't like the syntax of this commenting/api system.
It reminds me of the time where I overloaded the code to >not need< a documentation.
Btw, Nes', I have not (For example TextTag.) seen many (if any) of your resources using your suggestion?
The only thing you are using is library header.
About the function header: Put the stuff on the top and use a smaller and more useful comment block. This bloats code without usage.

 

[Magtheridon96]

The Function header shit is only useful when you have an isolated Function rather than a library.

It's all up to the user I guess.

 

[Nestharus]

No, I use the other stuff when I do professional code in something like c++. I don't bother with it in JASS/vJASS, too lazy ; p.

However, I also don't really use the lib header thing in c++. The API listing turns into a list of function headers and so on in a header file with prototypes in it =).


So then, considering this, do you not like the library header if it's by itself?

 

[Anachron]

I think you got me wrong.
I like the library header, but the other stuff is not good for vJASS imho.

 

[Nestharus]

Yea, in languages without prototypes/headers, you use the library header one. If they do have prototypes, then you use the function, struct, etc headers and no library header.