FRIHOST FORUMS SEARCH FAQ TOS BLOGS COMPETITIONS
You are invited to Log in or Register a free Frihost Account!


What documentation standards should be used?





boinsterman
What documentation standards should be used? As a mostly self-taught coder, I would not know what documentation is expected of me when I work for someone else.

I try to just put a few comments in my code and have clear variable names. If I am having a problem with a specific section, I put alerts or other text messages at various checkpoints.

Any sites out there that discuss this?
Marcuzzo
Some people love excessive documentation, others hate it, some believe that your code should be self explanatory, others believe that that's what documentation is for.

I'm a huge fan of WELL documented code AND intuitive code. ( especially for compiled languages as the compiler skips the documentation, for php... no idea if documentation has a performance impact )

your code should already be intuitive but still, how many times have you opened a piece of code in a text editor weeks, months, years after you last edited it and didn't have a clue as to how you took care of a 'problem'. this is where documentation comes in.

I systematically document everything in my code while writing it.
for:
- variables, properties and constants I usually add a @description, @date, @since, @type
- Functions, methods: @date, @description, @param[s], @return, @throws
- Classes: @date, @[class]desc,


I do most of my php coding in eclipse and if you add documentation to your methods, properties, classes, whatever, ... it will show this when you are using them.

then there is PHPDOC which can be used to generate html files with your documentation. I don't really use it because I can see the documentation in my IDE.


for small projects this is serious overkill but bad habits are hard to get rid of so I try to stick to my 'coding convention'.
as a matter of fact, for bigger projects documenting your code is a must!

here's a link that you can quickly read: http://www.mediawiki.org/wiki/Manual:Coding_conventions/PHP#Comments_and_documentation
boinsterman
Other people don't see my code except online, in forums like this or in webpages I put up. (I live in the Maine countryside.) I basically document for myself. I'm not involved in any large websites with thousands of lines of code, so remembering details of my projects is comparably easier than for those in such an environment.

But I want to start earning money through freelance or work-from-home projects, so I suspect I will need better documentation standards. My writing skills are good.

Most websites, however, have little client-side documentation, such as with javascript. Script libraries like compressed JQuery are a good example. They use up less memory this way, and I suspect that is why. But it does make it harder to wade through. And mapping out the HTML in an existing large page can be a bit daunting. I suspect documentation could help here as well.

But such documentation is intended mainly for the site's programmers, not others who might steal a company's ideas. So it looks like most professional documentation is done independently?
Marcuzzo
Php code and comments are not exposed to the browser. So I would say comment everything.
I usually 'build' my javascript in node with grunt and requirejs.
The source Will have comment but the build Will be minified.

EDIT: Editted the typo
boinsterman
I think I'm going to have to translate this one (from Geekspeak?):

Marcuzzo wrote:
Php code and comments are not exposed to the browser. So I would say comment everything.
I usually 'build' my javascript in node with grunt and requirejs.
The source Will have conment but the build Will be minified.


php not exposed to browser--This I knew.
You put your javascript in script libraries, presumably with different permissions than the webpages?
node = script library?
grunt = hard work?
requirejs = script library?
"build Will be minified" = the browser builds an executable version of the javascript code after loading?
"conment" = "comment" and not "condiment" (Waiter, could you bring some mustard for my keyboard?)
Marcuzzo
boinsterman wrote:
I think I'm going to have to translate this one (from Geekspeak?):

I'll just ignore that part, Shocked

boinsterman wrote:
php not exposed to browser--This I knew.
yaaay

boinsterman wrote:
You put your javascript in script libraries, presumably with different permissions than the webpages?

not sure where you got that, I don't think that permissions are set on javascript files ( at least I don't do it)

boinsterman wrote:
node = script library?

Wikipedia Page wrote:
Node.js is a software platform that is used to build scalable network (especially server-side) applications

see NodeJS
I basically use it to run Grunt.

boinsterman wrote:
grunt = hard work?

on the contrary, Grunt is a task runner. you define a set of tasks for example uglify : used to strip comment and carriage returns/line feeds, basically a compressor.

***EDIT: at first it's scary... it took me a while to get started on this one but after a while it get's really easy***END EDIT

boinsterman wrote:
requirejs = script library?

RequireJS is a file and module loader. this allows you to write your library in a modular way so you don't have everything packed into 1 source file but spread across modules.

boinsterman wrote:
"build Will be minified" = the browser builds an executable version of the javascript code after loading?

Since we are not actually building an executable, the 'build' term is actually misplaced.
I call it build because everybody seems to be calling it that way, but it is actually compressing, uglifying and packing all the source files into a single javascript file.

boinsterman wrote:
"conment" = "comment" and not "condiment" (Waiter, could you bring some mustard for my keyboard?)

typo... me a-so solly

English is not my native language, so please forgive me for any errors in my posts.
codersfriend
just always try to keep yourself up to date with the latest php documentation standards. I think the latest php now is 5.5
boinsterman
[quote="Marcuzzo"]
boinsterman wrote:
I think I'm going to have to translate this one (from Geekspeak?):
I'll just ignore that part, Shocked


I hope I did not offend you. That was not my intent.

American infantry (which I used to be in the Army Reserve) often are called "grunts". While some might consider it derogatory, which often felt a certain pride from it. It distinguished us from others and also implied a willingness to work hard or do "grunt" work, and possibly a few other things. The "uglify" portion associated with "grunt.js" fits right into that cultural framework.

This was the spirit of my "geekspeak" comment. Also, it implies the speaker has technological knowledge beyond that of the listener.

I had not been aware of these additional, publicly available script libraries. Those I was aware of are JQuery, JQuery Mobile, Mootools, YUIgraphics, and Google's map scripts. I have done very little with them.
Peterssidan
codersfriend wrote:
just always try to keep yourself up to date with the latest php documentation standards. I think the latest php now is 5.5

The documentation itself is not a documentation standard. A documentation standard tells you how to document your code.
Related topics
Intel, Sprint connect on WiMax
IBM backs Firefox in-house
Windows Tips&tricks!
Okay, I'm done trying to use CSS for layout.
php sessions
anyone has used tempelates?
[SUGGESTION] Crack down on spelling, grammar and spam
How To : Improve Your PHP Programming
How To : Secure Your PHP Website
Creating a new Operating System
SQL Basics
Java tutorials
Happy Birthday Frihost
learning from Opensource!
Reply to topic    Frihost Forum Index -> Scripting -> Php and MySQL

FRIHOST HOME | FAQ | TOS | ABOUT US | CONTACT US | SITE MAP
© 2005-2011 Frihost, forums powered by phpBB.