I have a page that is generated which inserts an HTML comment near the top of the page. Inside the comment is a *nix-style command. <!-- command --option value --option2 value2 --option3 --> This comment breaks the page completely. What is wrong with the comment to cause this to happen, and why is this the case?...
I usually comment "ifs" and write in "human language" what it means, like "checks if it's A or B". I find it's better for junior programmers that read the code to read what it means first and then analyse the statement (also for me when I'm checking old code) What do you do? What about other scenarios? Pros? Cons? ...
Im currently writing my bachelor thesis with latex and using TexnicCenter. I want to be able to send my generated pdf file to people and they should be able to write comments. It seems like commenting is not allowed by default, how do I change this? I am using straight to PDF with pdflatex and acrobat reader 9 to read and comment on the...
This question would probably apply equally as well to other languages with C-like multi-line comments. Here's the problem I'm encountering. I'm working with Java code in Eclipse, and I wanted to comment out a block of code. However, there is a string that contains the character sequence "*/", and Eclipse thinks that the comment should en...
Is there a standard convention (like phpdoc or python's docstring) for commenting C# code so that class documentation can be automatically generated from the source code? ...
What are the different standards and practices of code documentation and which have worked best for you? I ask because myself and friend are starting a company and will probably need to have some agreed upon standard for commenting things so that we can read each other's code more easily. ...
What is the most efficient way to determine how many comments a particular blog post has? We want to store the data for a new web app. We have a list of permalink URl's as well as the RSS feeds. ...
I've recently started a new project and I'm using C# for the first time. I've found that while Visual Studio is helpful in creating C#'s XML comments to document your classes and methods, there's not much you can do to generate MSDN or Javadoc style documentation. Google tells me that Visual Studio 2003 included a tool to generate such...
I wrote a simple tool to generate a DBUnit XML dataset using queries that the user enters. I want to include each query entered in the XML as a comment, but the DBUnit API to generate the XML file doesn't support inserting the comment where I would like it (above the data it generates), so I am resorting to putting the comment with ALL ...
Do you often see in API documentation (as in 'javadoc of public functions' for example) the description of "value limits" as well as the classic documentation ? Note: I am not talking about comments within the code By "value limits", I mean: does a parameter can support a null value (or an empty String, or...) ? does a 'return value'...
What common comment tags do you find useful, and how do you use them? For instance, we standardize on: //TODO: blah blah //FIXME: blah blah //NOTE: blah blah We have an IDE plugin that is able to pick these up project wide as a reminder. Do you use any of these aide memoirs? How do you use them? Are they useful? Do you find there a...
Hi everyone, I'm using VS2005 in a solution with a mix of VB and C# in different projects. I use this solution on several different computers and XML comments with both /// (c#) and ''' (VB) have been fine for months. all of a sudden, on my main development machine, they've stopped working in VB. They still work in C#. They work in o...
Is there a code/comment ratio that you consider to be a sign of good (bad) code health? Can you give examples of open source projects that are considered to be well coded and their respective comment ratio? (I realize that no ratio is "true" for every project and there may very well be crappy projects that exhibit this theoretical gold...
I would like to create a blog where my Twitter updates essentially create blog posts, with a comment thread. If there isn't blog software that does this right now (I did some searching but couldn't find the commenting aspect) what would be the simplest approach and starting blog software to do this? Potentially an alternate approach to ...
What are your best practices for comments? When should they be used, and what they should contain? Or are comments even needed? ...
When you need to obsolete a section of code (say either the business rules changed, or the old system has been reworked to use a new framework or something) do you delete it from the file or do you comment it out and then put in the new functionality? If you comment it out, do you leave a note stating why it was removed and what it was ...
Some of my colleagues use special comments on their bug fixes, for example: // 2008-09-23 John Doe - bug 12345 // <short description> Does this make sense? Do you comment bug fixes in a special way? Please let me know. ...
I'm used to atlas where the preferred (from what I know) method is to use xml comments such as: /// <summary> /// Method to calculate distance between two points /// </summary> /// /// <param name="pointA">First point</param> /// <param name="pointB">Second point</param> /// function calculatePointDistance(pointA, pointB) { ... } R...
When writing "library" type classes, is it better practice to always write markup documentation (i.e. javadoc) in java or assume that the code can be "self-documenting"? For example, given the following method stub: /** * Copies all readable bytes from the provided input stream to the provided output * stream. The output stream will...
For those of you who have looked at Reddit's source code, where exactly is the logic where it manages the comments hierarchial structure? I downloaded the code, but couldn't even find the database structure let alone where the reads and writes are for the commenting. Is it doing updates on lots of comments if someone replies to someone...