[MP2]

I've been working on a server for about a year now, and it didn't get very far for many reasons. Low motivation, bad layout, poor coding standards and practically no documentation at all are but a few.

I've definately improved since making those topics, and definately see the advantages of using many included files as opposed to having everything in a single .pwn file (that's just stupid and I realise so now!).

I made this topic to discuss with you all (especially those with experience with major projects) how to go about documenting your stuff. I had a short conversation with Gamer_Z a few days ago about this, and he referred me to this: http://www.stack.nl/~dimitri/doxygen/ It seems way too much for a SA-MP server though. I think it would confuse me more than help me.

My main 'concern' is this: I create a function, for example, CreateDoubleRainbow(), and it's in some file in my server files, for example /scripts/core/objects/blah/dir/lol/rainbows.inc

If I want to edit that function 3 months down the line - how do I find it? I clearly need to document WHERE it is, WHAT it does and HOW to use it, but I'm not too sure how to go about that. At one point I thought of creating a wiki for it, but that seems a bit weird for some reason, not really the done thing.

Discuss!

[playbox12]

You'd include it so that would give you the directory to where it is stored wouldn't it?

Anyway, I don't think finding it should be your main concern, rather, you should document how the code works, what input it requires, what does it output and how does it process it. With small functions you can remember it, but when you make big, complicated functions or systems you'll lose track. I'm sure you know that already though.

Y_Less documents his code quite well in stuff that he releases (YSI for an example). It gives a good explanation per function on exactly what it does.

What I do myself is, on the top of my main file, I make a small template on how I document functions. This template I then copy over to the top of the function, I usally list the name, parameters, output and what and how it processes it. Code however should speak for itself if you write it well, but from my experience in PAWN you have to use weird hacks and manipulation sometimes to get what you want, so properly explaining what it does will help you in the long run.

Now I'm not very good at this myself, and I often lose track because I use a different variable name for something in another context, which throws me offtrack. This has lead me to actually make a system twice (after I took a break for a month or so) because I thought I never made it. Maybe a good list on what exactly is done, and what functions are linked to that would help.

[Bakr]

You should be able to locate the functions and variables simply by the file and its path. Otherwise it is set up poorly.

[Cell_]

Quote:

Originally Posted by MP2 My main 'concern' is this: I create a function, for example, CreateDoubleRainbow(), and it's in some file in my server files, for example /scripts/core/objects/blah/dir/lol/rainbows.inc

That is the main problem (I mean I won't even hide my p*rn files in that many sub-folders). You have taken the "using many include files" too literally. Don't use a new include for each and every function you create, that's just a mess (according to me). Try to use a different include file for a specific system, for example, if you're creating a weather changing system, use a specific include for that which contains all the functions related to weather changing only. This is one way. You can store them include/systems/*.inc

The other way, is to use a different include for every type of code (this can get a bit messy). I cannot express myself but what I mean is to make a specific include containing all the functions, a specific include for all the variables, for all the macros, defines etc. You can store them as include/*.inc

Using one of these methods, you know where something is. You're concerned with changing a part of the code in your weather changing system, you look for it in the 'weather.inc' or if you want to change a function, you search the 'functions.inc' rather than searching for it in multiple directories.

[MP2]

Perhaps my example was a little extreme; I'd never use silly-deep directories like that. I have often found myself wondering 'what file is that function in' though. I just need to be more organized.

[Basssiiie]

Quote:

Originally Posted by MP2 I have often found myself wondering 'what file is that function in' though. I just need to be more organized.

What about this: make a text file and make a list with the name of every function, plus the name their corresponding include file. If you do this, you only have to do CTRL+F, find the correct file name and you've got your function.

Another option is to use some program which can search through multiple files. I know Notepad++ had this function, labeled "Find in Files", which allows you to find a certain function in a whole directory. For example, when I search "format" in my include directory, it prints this:

Code:

  C:\Users\bas\Desktop\Test Server\pawno\include\a_npc.inc (3 hits)
	Line 28: native printf(const format[], {Float,_}:...);
	Line 29: native format(output[], len, const format[], {Float,_}:...);
	Line 29: native format(output[], len, const format[], {Float,_}:...);
  C:\Users\bas\Desktop\Test Server\pawno\include\a_samp.inc (6 hits)
	Line 55: native printf(const format[], {Float,_}:...);
	Line 56: native format(output[], len, const format[], {Float,_}:...);
	Line 56: native format(output[], len, const format[], {Float,_}:...);
	Line 65: native SetTimerEx(funcname[], interval, repeating, const format[], {Float,_}:...);
	Line 69: native CallRemoteFunction(const function[], const format[], {Float,_}:...);
	Line 70: native CallLocalFunction(const function[], const format[], {Float,_}:...);

[ And after that it prints every other include which uses the word "format"...]

[MP2]

Quote:

Originally Posted by Y_Less pawncc has a "-r" switch - you might want to look it up.

I'd like to, yes, but I can't find anything on it anywhere.

[Basssiiie]

Quote:

Originally Posted by MP2 I'd like to, yes, but I can't find anything on it anywhere.

From the Pawn manual:

Quote:

-r filename Report: enable the creation of the report and optionally set the filename to which the extracted documentation and a cross-reference report will be written. The report is in “XML” format. The filename parameter is optional; if not specified, the report file has the same name as the input file with the extension “.XML”.

:3

[cessil]

I think this is very relevant
http://www.makinggoodsoftware.com/20...ing-variables/

if you have to write down where each script is then it's too complicated

[thefatshizms]

What I do to find things is:

Have many includes for each thing
A main include which includes all those includes and comments below each include saying what they are and what's in them
And last I have my main .pwn file which includes the main include so I can compile.

Btw I use visual c++ 2010 (solution explorer is awesome)

[Dan..]

Quote:

Originally Posted by MP2 I'd like to, yes, but I can't find anything on it anywhere.

Check Pawn manual. They are called "documentation comments". Here is a nice tutorial and here is an example of output.