It seems that there is no real pattern to the way functions are named, str_replace, strrpos, strip_tags, stripslashes are just some. Why is this the case? EDIT - this wasn't meant as a "troll" type post - just something that I think everytime I use the language! ...
The people writing the user manual are not necessarily programmers, and they need a visual editor. A major issue is the internal format of the authoring tool; it should be readable text/html, so it's easy to compare versions of individual pages checked into version control. ...
I am supposed to write "detailed" design documents for my job, but I always find myself overspecifying parts and getting burnt out when I realize I can't specify everything exactly in the doc or I would basically be writing the code all over again! Is there a good rule of thumb when it comes to writing design documents to help guide me ...
Java has its own (self-documented) Javadoc, PHP has PHP.net, all the MS documenation can be found at the MS Developers Network, but whenever it comes to throwing together some C++ my first stop is always Google. To all the C++ developers out there, what's your one-stop-shop? ...
I was wondering if anyone has some best practices to follow when diagramming distributed systems. Not being much of a visual designer I typically go through hours and several iterations till I reach the point where I feel the diagram matches the system. Of course after I show it to someone else I spend more hours cleaning and rearranging...
What reasons could ease the choice between clear and concise artificial code example versus real-world working code which might be accompanied by all gory details for an author of programming book or a participant in online discussion? ...
Hello, I started using Sandcastle some time ago to generate a Documentation Website for one of our projects. It's working quite well but we've always only written documentation for classes, methods, properties (...) in our project and had completely separate documentation for the overall project and project parts/modules/namespaces. It ...
Every project we do we need to create user guide. The problem with most user guide is that alot are full of text and not screenshots etc. Anyone seens any nicely done user guides? Or even some kind of flash UI to orient user to the website? etc.? ...
I am using Apache's Velocity templating engine, and I would like to create a custom Directive. That is, I want to be able to write "#doMyThing()" and have it invoke some java code I wrote in order to generate the text. I know that I can register a custom directive by adding a line userdirective=my.package.here.MyDirectiveName to my v...
What are good arguments to convince others to comment their code? I notice many programmers favor the perceived speed of writing code without comments over leaving some documentation for themselves and others. When I try to convince them I get to hear half baked stuff like "the method/class name should say what it does" etc. What woul...
Suppose that you are writing or maintaining a piece of code that uses some API that you are not 100% familiar with. How do you decide whether to read the documentation of a certain call target, and how much time to spend reading it? How do you decide not to read it? (Let's assume you can read it by opening the HTML documentation, insp...
I have the following piece of code in my jsp : <% pageContext.setAttribute("warnings",Globals.WARNING_MESSAGES); %> <c:choose> <c:when test="${requestScope[pageScope.warnings] or sessionScope[pageScope.warnings]}"> <html:errors header="warnings.header" footer="warnings.footer" prefix="warnings.prefix" suffix="warnings.suffix"/>...
I am very likely to be starting a new project at work and will need to use the Java Swing library. I would like to get up to speed pretty quickly, preferably in the next two months. What do you consider to be the best documentation (either online or in book form) to help me get a solid grasp on the library? ...
What are your "favourite" overuses / misconceptions about commenting the code? Why do you sometimes think commenting is a pain? What arguments would you use to convince others that less is more at commenting in some cases? This is the negative counterpart to How to convince people to comment their code - such that it remains a collecti...
I am using Doxygen to generate HTML documentation from my code. However I find that default stylesheet has quite poor choice of fonts and layout. I know I can write my own CSS file to get exactly the output I want, but before I spend my time on it, I am wondering if there are any decent custom stylesheets already available. ...
Hello everybody! Today I had an argument with a colleague about one of his comments as summary of a method. Mostly he is not writing any summaries but in this case he added one and it was a really bad one: It was not described what the method is doing, it assumed what the method maybe is doing. I have to add that this piece of code was ...
I am always wondering what should I write for inline code documentation? I always end up with one liners "This function does x" or a 4 paragraph essay describing every micro detail of the function. I am trying to find a balance that provides good documentation without being to verbose. So if you could replay with the one thing that yo...
I read Richard P. Gabriel's book "Patterns of Software" (pdf) which contains an essay called "Writing Broadside" in which he contends that programmers should develop their ability to write clearly. I have found that his suggestions have definitely improved my ability to write tech. spec's and design documents. One of his suggestions is ...
We have a large system that processes logs from a very large web site. By large I mean a site that has more than 300,000 updates per day. Yes. Per day! I've just finished an update to this system to correct a bug. Part of the problem doing the work was a lack of documentation for the system. Most questions were met with "Ask Andre, he'l...
Hello, I have always been for documenting code, but when it comes to AJAX + PHP, it's not always easy: the code is really spread out! Logic, data, presentation - you name it - are split and mixed between server-side and client-side code. Sometimes there's also database-side code (stored procedures, views, etc) doing part of the work. T...