Do you guys think inline documentation can be a good coding practice?
Especially for PHP (other "typeless" scripting languages) as you cannot explicitly declare functions and properties of a class as private/public. And you cannot specify the datatypes of variables and function returns.

Could this be an alternative to having to name variables with type information?

I would never ever dare opposing an expert with a 30 year of coding experience, however, maybe it is my missunderstanding, but still Macromedia products seem to be "THE PRODUCTS" for web development.

Let's just clarify - users that stick to the quick-add buttons, draw table layots and stuff are the ones you don't count, is that correct?
I have been using MM tools since Dreamweaver 3 when I took my first steps in web design. That is how I learned - in split screen, watching the code change. Now I use it the other way arround - still in dual view, writing the code and watching the changes in the preview screen .

Now, as an MM user, I really enjoy the code assistance it provides - the auto tag closing functionallity, the code hints, the Reference it has as help, and of course - code colouring that is trully helpful in error finding. And you say the code is dirty...well...obvioursly you have never ever tried to re-code or edit a page created by MS Office products....well that is a dirty code. A page with tabular data, exported from WORD as a web page, had an output of 350Kb.!!! After automated Macromedia word clearing functions it was reduced to 60kb. After a complete cleaning, sticking to css rules and reduction of unnecessary code, at the end I got a really nice page, looking the same way as in word, still - only 20Kb TOTAL. Well that is a messy code...

Now - about standards - a few years ago, when "the browser wars" raged, we all have seen the pro-ie or pro-Netscape coding. You all remember what a complete mess it was - a website saying - you have to utilize this resolution and IE preferably. Now, after the css and web standards in general are supported by more and more coders, and more and more browsers(although there are some differences), I find it much more easier and really much better to code a page. I try to stick to the standards and avoid the "hacks" in order to achieve what I want, and I do so, because the hacks won't work tomorrow. Another thing is - another guy may support this website tomorrow, so why should he reinvent or rewrite the complete code - he has just change the "skin", the bones are always the same.
It is the same way for me in php / javascript when I code. I try to make the code more clear, more user-friendly, and eventually I try to leave as many code hints and in-line comments to support myself, or the coder after me - you can never remember what the hell you were thinking 2-3 months ago when you coded a page, unless you have hints or comments...and what about the things you coded an year ago?

Indentation is readability. True that no indentation or no whitespaces saves bandwith, but, I don't think that at present and maybe in near future there will be a problem with the bandwidth - I could not imagine a download speed of 60K 2 years ago(at least not here in Bulgaria), still, today if you drop below 50k your provider sucks . Soon we will see such speed even on mobile devices, so ... how much whitespace-saving will spare from the bandwidth?!

And at last, but not least - If you want to improve, you have to learn every day. I grasp new ideas from the other coders on the web, by reading the code of the pages I like, and I would be glad if yonger coders are able to get ideas from the pages I've done, and that is how the web will go better every day. And what makes me sad is that there are a lot of web coders that just do it for the money, regardless of the messy, full of errors, not corresponding to the standards code they produce.

Keep it pure I would say

i comment as much as i can, but only in short bursts. when commenting how a function works, i might write a few lines, but otherwise, i just comment a couple words explaining the next block of code. i find it easier to read through a little well written code with a brief comment than a chunk of code with lot of commenting.

and usually, when variables are named with type/scope, i find i don't even have to look at commenting. when i see "strName", "objName", "and "gstrName", i know i am probably looking at the string for a name, maybe the sql results for a query regarding a name, and a global string for a name, respectively. seeing those vars named "name", "query", and "name", you can't tell scope or type.

my main gripe, not directed towards anyone specifically, is that these are basic programming 101 practices that you will be taught in any intro class when dicking around with VB6, or whatever. php shouldn't be any different, they are still variables, they still have a type, they still have a scope. just because php isn't strict about data types doesn't mean that coding principles should be more lax. indenting, naming, standards, these all effect readability and overall quality of code and lack thereof, in any other languages, are all signs of amateur coding.

ahah... same here, i think 1hour's documentation to 10 hour's coding is a reasonable ratio... it's not just laziness either; i might change something, and then I'd have to rewrite the documentation aswell as the dependancies =P

i don't like inline comments anywhere. just big explanative descriptions infront of functions or at the end of each file. i like doxygen/javadoc type tools; that make funky documentation minisites based on "super comments" in code. commenting inside functions; only ever to disable parts of the function, or to say "//\todo FIX THIS!" or similar

i would certainly never comment HTML except as a means to prevent it being displayed temporarily; i indent HTML to my own style - completely rigid nested indentation rules makes some files look like the himalayas sideways

[I enjoy the pleasures of what CSS-only hippies would call 'bad practices' in HTML; but those practices exist out of neccessity more than choice.]

i think languages like PHP, Javascript, and to a lesser extent Perl (and others, [ including VB6 without Option Explicit]), almost encourage lax instantiation of variables, and maybe "bad programming practices"; just because they allow it to be done, if they didn't allow it, people wouldn't do it. but because the interprettor doesn't care, certain developers don't care.

in my opinion; it's even MORE important with an interpretted type-loose language to follow , at least some kind of standard. it's much easier to make stupid mistakes than with a strictly typed language.

but saying that, i take much more pride in work that i do in compiled languages than i do with work in interpretted languages.. perhaps it's because i see interpretted languages as temporary testing platforms for concepts; and that work in them will be generally harder to maintain.. or maybe i just have all that free time while compiling to tidy things up... :rolleyes:

I want to address the inline comments issue... In interpreted languages, comments = processor overhead... so use them effectively, yet don't abuse them. In compiled languages comments = compiler overhead, but that is a 1 time deal and the overall effect is only felt if you are compiling a application that takes hours to compile... Then I say, err on the side of abuse...

The more you comment you code, the easier it is for you or someone else to redress it later... Large intro comments for Javadocs or similar are fine for explaining what a class or method is for, but they don't help someone understand "how" it is doing it...

I am the CEO now, and though I insist in continuing to wrote code along with my developers, my developers are very thankful for the amount of comments I placed in the code when the company was young and I did 99% of the work myself...

I have just initiated a rewrite of PHP code I wrote 6 years ago. The developing team would have to rewrite the code completely if they didn't have my robust comments....

I am also initiating a new codign project which will use Java and JSP. The requirements for the development team will include robust commenting... I PAY them for the commenting & coding time, so I expect robust comments, there is no excuses otherwise.

Now, for the comments above about "how" one uses Macromedia and/or Word... I guess I would first say that I have had the opportunity to work with output from many editors than most people. I have used Macromedia products as well as many others, always looking for a "faster" way than hand coding... In the end, I found some good tools that work as RAD environments b ut allow me to keep the power and flexibility of hand coding...

For the guy who codes in MM's code window and views the changes in the preview window, I would say that is a fine way to do it... and you can probably get clean code... the messy code comes from letting the MM code engine do the work for you... You can always tell because you will end up with code fragments that are superfluous... for example

<span style="font-size: 18pt;"></span>
empty span tags is common...

<a href="#"></a>
empty anchor tags is common...


etc.

The important thing is that you stay in control of the code, not let the application control the code...

I want to be clear, also about naming conventions, I agree that good naming conventions are a must, especially on large or distributed projects... But there is more than 1 way to skin a cat, Why anyone would be skinning cats..I don't know... But to claim it is "mature" coding to use 1 method because it was taught in some book and/or some class in basic programming is just rediculous... VB developers adopted those techniques because they had 1) a limited selection of variable types 2) only moderate variable typing.... There are languages that FORCE specific constructs for certain variable types... Basic, which is where MS started when trying to build VB, was one... Such as String variable must begin with "$", etc. These were common... people who worked with the old languages got used to the visual representation of type, and thus when VB, etc. were more name friendly, they searched for a way to maintain that clarity...

I use iNum, sNum, isNum, hasNum, lNum, dNum, fNum, etc. which are C & C++ common naming conventions... camel case and all.... I am sure most of you looking at those have NO trouble figuring out what TYPE each of them would hold...

THUS, my comment, just because it woks for you, doesn't mean it is "right" for everyone, and just because some teacher told you this is the way I expect to see your code does not make it the way everyone should code...

My first CS teacher, back 27 years ago, told me I had to completely plan the code, even write it down before coding a single line of code... he said that this was "good" programming practice.... I NEVER did.... I found that I could code directly into the machine with better accuracy than on paper, I also had bad handwritting... and I felt that code TWICE was a waste of my precious time... I would code it, debug it, add a few bugs on purpose, print it, then fix those added bugs, and print it again... Then I would have him signoff the buggy version as draft code and sign off the fixed version as final code...

He took the app and code printouts and examined them to determine grades... I always got an "A"... I had to add the bugs because perfect draft code was very unlikely in the best of cases, and he would have realized I was NOT following instructions 100%...

The point is, "mature" programming is finding a way that works for you and being consistent... NOT following someone elses rigid ideas... If you are consistent, then you will have easier times understanding your own code months or years later, and others will get adjusted to your coding style when you work in a team, even if you don't have 100% the same styles... AND good comments, inline, make the difference when you are adjusting to the new guys...

I love the conecpt of Javadocs, BUT Javadocs can use inline comments too, if written correctly... The trouble is most developers don't give enough information in the comments, before during or after the code to make the Javadoc generated comments very useful...

I see javadocs with VERY useless information frequently...

I absolutely agree with this.

I have worked in PHP now for several months, Java about a year, C++ a few months, and I have found that apart from the awful mess of HTML indenting (3 nested tables, and half ur working space is gaps ;x), that proper indentation, casting, variable types, indentation and uses of classes is critical to the further enhancement of software development projects.

It is critical that when software is designed, it is not designed using short sightedness of a sole programmer who's coding standard and structure is a royal mess.
As I myself having taken a PHP development position (my first actually ), I have come to realisation, first of all which I already believed, that proper code flow, structure and indentation is at the outmost, critical for reusability, improvement and modification in time.
On top of that, proper documentation is vital, it cannot be said enough how important having documentation of a system is.

Modular programming practises imo, should be enforced in every teaching institution as a first programming method, and stress its importance. Each individual will develop their own methods and structures, but it is critical in team environments, and open source, that the same structure, and declarations etc. be consistent, the same throughout and properly documented/commented.

I myself am only 21, but I do know a thing or two about working in projects with other coders/developers/designers who can't design or code cleanly.

This goes back to my earlier comment that the indentation of HTML only becomes an issue when you have embedded tables, which is usually the result of tables being used for layout control....

Since "good" coding practices include not using tables for layout, then any pages, people, etc who suffer from the HTML indentation problem would indicate that someone didn't use "good" coding sytles anyway...

I am happy to hear you got a job coding PHP.... amazing for someone who has only been coding in it a short time...

very FEW professional projects have an assigned and/or documented ... convention for variable names... at least in my experience... a team that works long together may develop a standard system simply by conforming to one or anothers habits... often by conforming to the lead developer's habits...

I often find that names used in one component of an OOP large scale project may be completely different from those used on another... So they are not common throughout... but as long as they are reasonable & well commented and each person is consistent, it is not too difficult to pickup someone elses code, when they have a different style than you, read it, and understand it...

Yes that is true, it is easier to read and pickup on other coders style if they are clean and have good consistent naming convention, and at least some consistency throughout the project. My biggest annoyance so far, is the not-so-strict use of classes where they should be used, and the use of classes when they aren't needed. I find it easier to use classes not just for reuse, but also accessibility within a project, and easy enough to duplicate to other projects with minimal modification.

HTML indentation comes down to individuals preferences. I try to keep everything indented but it just becomes messy. For myself and reading code quickly and efficiently, I find that having structured and properly indented code is critical, as you can quickly scan sections to find where a problem, or modification/improvement can be achieved. I find it very difficult to scan long sections that are backed up against the wall with no flow or indentation, and all over the shop.
It may be time consuming, but I find that with properly structured code it is very easy for others to understand what you are trying to do.

But personally, I prefer the OOP approach, and I try at all times to program in the OOP methodology, and abstain from classical programming that uses inline functions, bad naming, and just including a horde of functions within a page that just are not needed at all, where classes have an advantage, and not only that, they are anonymous for data formatting.

At work, I have already cut rendering time 3 quarters down from its original on a specific page within a specific project, by using classes and low amount of includes (some of these files are includes within includes within includes, it took me an hour just to find one bloody function that didn't even do anything!). Lesson learnt - use classes.

Working with unindented and uncommented/undocumented code is a nightmare.

I think that indentation is essential; it makes reading code far easier and helps avoid simple mistakes matching stuff up.

On larger projects it doesn't matter what set of standards you stick to so long as everyone uses them and produces clean readable (and therefore maintainable) code is produced.

My rule of thumb is after every function, if its not obvious what it does at a glance or isn't a one-liner, add a quick comment saying what it does. If needs be give a quick example of use.

I stopped using those conventions when I started using object orientated languges... iNumber, etc, works ok for numbers, strings etc, but when you're using references to custom types/classes; what's correct?

Something like objReference is always going to work; but it's as bad as just 'reference', I suppose it's always possible to abbreviate a class: vctMyVector, lstMyList etc, but it's harder when using custom types/classes that have very literal names, I have an anecdotal 'box' class for example, that draws boxes ( as a classic example ) - so all references to objects of the box type can start with the prefix box - a'la boxTheBox; but I might have another class that acts as a 'box' of variables ( maybe a 3D array ), we have boxForDrawing, boxOfVariables, or drwboxMyBox, memboxMyBox... ahh... I like not...

So, I stick with short, unprefixed names that describe the context of an object within another; memoryPool for the memory box, drawObject for the drawing box. Heck I don't like camel notation either : so it'd be memory_pool and draw_object. Then, if I change the type of a memory pool to some 8 dimensional structure, it can still be a memory_pool, if I decide circles are nicer than boxes, it can still be a draw_object. I suppose I could have made it a shpDraw and a memPool to begin with; but it's seems like an uneccessary convolution - starting to use a convention that I don't believe is going to hold out indefinately - and because of my nature, if a convention doesn't work in one circumstance, it can't be the convention anywhere. So, for that reason alone, I divorced type prefixing very shortly after we first got acquainted...


This demonstrates, or perhaps at least allows me to draw attention to, one of the key principles of component programming. As long as the component works - it shouldn't matter what's going on inside it. That is, a 'component' implies a well encapsulated object or static library that provides a small - to - moderate, and very specific functionality. Public documentation for a component should be written from an external perspective, and external usages of that component should rely on exposed methods and interfaces... I suppose it's important for those methods and interfaces to follow some kind of convention; get_something( ), set_something( ), is_something( ), do_something( ) et cetera [ although the do is probably unneccessary there ].

-

On the subject of indentation... tabs or spaces ? =P I hate system tabs in program code ( because program/os one might say a tab is 2 columns, program/os 2 might say a tab is 8 columns ), but I don't mind them in XML/HTML/CSS/etc.. Perhaps that's because you can load up XML in document explorers, and they don't care about tabwidth..