Got to love well documented code

  • (2 Pages)
  • +
  • 1
  • 2

16 Replies - 1399 Views - Last Post: 04 November 2011 - 09:44 AM

#1 Duckington  Icon User is offline

  • D.I.C Addict

Reputation: 169
  • View blog
  • Posts: 606
  • Joined: 12-October 09

Got to love well documented code

Posted 27 October 2011 - 03:38 AM

Came across this gem earlier, in a script I'm supposed to be altering (2500+ lines).

if (($e = $t - $n - $s - $p) > 0)
{
	            mtrace ($e.' course(s) failed due to errors');
}



No comments, no explanation, and when I do eventually find the variables, the letters aren't even anything to do with that they are representing:

$t = 0; // Read courses
$s = 0; // Skipped courses
$n = 0; // Created courses
$p = 0; // Broken courses (failed halfway through



Love it.

Is This A Good Question/Topic? 0
  • +

Replies To: Got to love well documented code

#2 tlhIn`toq  Icon User is offline

  • Please show what you have already tried when asking a question.
  • member icon

Reputation: 5436
  • View blog
  • Posts: 11,653
  • Joined: 02-June 10

Re: Got to love well documented code

Posted 27 October 2011 - 05:38 AM

Maybe it was *supposed* to be that way.
Perhaps it was run through an obfuscation program like DotFuscator to make it harder to disassemble.

I notice that Dotfuscator will rename variable in alphabetic order, as they appear in the application. This really looks a lot like that.
Was This Post Helpful? 0
  • +
  • -

#3 DarenR  Icon User is offline

  • D.I.C Lover

Reputation: 433
  • View blog
  • Posts: 2,998
  • Joined: 12-January 10

Re: Got to love well documented code

Posted 27 October 2011 - 05:40 AM

At least it had something written-- here at work none of our code has documentaion unless I add it, which I generally do if I am working on a project.
Was This Post Helpful? 1
  • +
  • -

#4 Duckington  Icon User is offline

  • D.I.C Addict

Reputation: 169
  • View blog
  • Posts: 606
  • Joined: 12-October 09

Re: Got to love well documented code

Posted 27 October 2011 - 07:04 AM

View PosttlhIn`toq, on 27 October 2011 - 06:38 AM, said:

Maybe it was *supposed* to be that way.
Perhaps it was run through an obfuscation program like DotFuscator to make it harder to disassemble.

I notice that Dotfuscator will rename variable in alphabetic order, as they appear in the application. This really looks a lot like that.



Nah it wasn't.
Was This Post Helpful? 0
  • +
  • -

#5 tlhIn`toq  Icon User is offline

  • Please show what you have already tried when asking a question.
  • member icon

Reputation: 5436
  • View blog
  • Posts: 11,653
  • Joined: 02-June 10

Re: Got to love well documented code

Posted 27 October 2011 - 07:06 AM

That's just sad. Sounds like first year students or Mumbai outsource.

Or someone that did it deliberately to maintain job security.
Was This Post Helpful? 0
  • +
  • -

#6 xclite  Icon User is offline

  • LIKE A BOSS
  • member icon


Reputation: 894
  • View blog
  • Posts: 3,153
  • Joined: 12-May 09

Re: Got to love well documented code

Posted 27 October 2011 - 07:10 AM

Doesn't have to be Mumbai - you should see some of the stuff the Navy comes up with when it isn't tactical.
Was This Post Helpful? 0
  • +
  • -

#7 tlhIn`toq  Icon User is offline

  • Please show what you have already tried when asking a question.
  • member icon

Reputation: 5436
  • View blog
  • Posts: 11,653
  • Joined: 02-June 10

Re: Got to love well documented code

Posted 27 October 2011 - 07:23 AM

Yeah. I was US Army Signal Corps. Pretty bad there too.
Was This Post Helpful? 0
  • +
  • -

#8 Martyr2  Icon User is offline

  • Programming Theoretician
  • member icon

Reputation: 4312
  • View blog
  • Posts: 12,090
  • Joined: 18-April 07

Re: Got to love well documented code

Posted 27 October 2011 - 10:20 AM

I run into stuff like that from time to time. Really makes me a sad panda. I hate it when people's ego, fear of being replaced, inexperience, laziness and political issues get in the way of writing some half way decent code and document it. I have built half of my career on the fact that I go into a company and turn their code garbage into code gold. I feel like Rumpelstiltskin except I don't get anyone's first child (maybe that is a good thing!).

Word to all the newbies out there, write great code and leave the fear of it "being stolen" or your political views out of it. If everyone sees your nice code, they may take it but everyone will still know you are the genius of the group.

:)
Was This Post Helpful? 1
  • +
  • -

#9 pietomb00  Icon User is offline

  • D.I.C Head

Reputation: 12
  • View blog
  • Posts: 68
  • Joined: 28-June 11

Re: Got to love well documented code

Posted 31 October 2011 - 08:29 AM

Had something similar the other day, a colleague and I were tasked with documenting an entire program for some completely non-technical business people to try to understand, because the person who wrote it had only been there a year and left without explaining it.

My favorite bit was coming across and important bit with a comment saying
'this should work but it does not


Was This Post Helpful? 2
  • +
  • -

#10 sbromley  Icon User is offline

  • D.I.C Head

Reputation: 21
  • View blog
  • Posts: 127
  • Joined: 20-May 09

Re: Got to love well documented code

Posted 01 November 2011 - 02:14 PM

Wouldn't you feel a little embarrassed if someone came across your code and they didn't understand what was going on at all? It always feel more complete when there is JavaDoc, inline comments and a wiki about all the stuff I just implemented.
Was This Post Helpful? 0
  • +
  • -

#11 cfoley  Icon User is offline

  • Cabbage
  • member icon

Reputation: 1940
  • View blog
  • Posts: 4,027
  • Joined: 11-December 07

Re: Got to love well documented code

Posted 01 November 2011 - 04:11 PM

I think I'd enjoy the challenge of deciphering it, giving things meaningful names and refactoring it as necessary. Of course, that would only work as a hobby or if I had a REALLY understanding employer.
Was This Post Helpful? 0
  • +
  • -

#12 fromTheSprawl  Icon User is offline

  • Monomania
  • member icon

Reputation: 513
  • View blog
  • Posts: 2,056
  • Joined: 28-December 10

Re: Got to love well documented code

Posted 01 November 2011 - 06:40 PM

Question guys and girls! How do you document your stuff? I first started documenting using JavaDoc then I added OneNote to my documentation tools.
Was This Post Helpful? 0
  • +
  • -

#13 no2pencil  Icon User is online

  • Toubabo Koomi
  • member icon

Reputation: 5178
  • View blog
  • Posts: 26,872
  • Joined: 10-May 07

Re: Got to love well documented code

Posted 01 November 2011 - 06:42 PM

I once left curse words in my comments for code that I sent to the copyright office. Ooops :P
Was This Post Helpful? 1
  • +
  • -

#14 Zachari  Icon User is offline

  • New D.I.C Head

Reputation: 4
  • View blog
  • Posts: 22
  • Joined: 28-February 11

Re: Got to love well documented code

Posted 01 November 2011 - 09:45 PM

I would be absolutely appalled. I find that proper documentation is half of the job. How do you work in a team environment without the ability to properly name and document?
Was This Post Helpful? 0
  • +
  • -

#15 Duckington  Icon User is offline

  • D.I.C Addict

Reputation: 169
  • View blog
  • Posts: 606
  • Joined: 12-October 09

Re: Got to love well documented code

Posted 02 November 2011 - 03:00 AM

View PostfromTheSprawl, on 01 November 2011 - 06:40 PM, said:

Question guys and girls! How do you document your stuff? I first started documenting using JavaDoc then I added OneNote to my documentation tools.


Depends really, I don't have a standard that I always use. But generally it would be something like:

/*
* Explanation of what the file does in English terms
*
* List of any other files which I changed/created which are required for this file to function.
*
* @author
* @license
* @Etc...
*/

/**
* Explanation of class
*/
class
{

/**
* Explanation of function
* @param type brief explanation
* @return type brief explanation
*/
function(){

// Brief comments for specific lines, E.g. Loop through rows
foreach($row AS $key => $val):

// Construct Query

$sql = "";
$sql .= "SELECT * FROM t1";
$sql .= "JOIN table2 t2 ON t1.field = t2.field";
$sql .= "WHERE t2.field2 = 42";
$sql .= "ORDER BY t2.field3 ASC"; #Inline comment to explain something small

// Execute query and return object
$qry = mysql_query($sql);
$obj = mysql_fetch_object($qry);

endforeach;

}

}


[...]

Etc...




Plus change log file if it's a large project and/or I'm changing things that someone else has one previously.
Was This Post Helpful? 1
  • +
  • -

  • (2 Pages)
  • +
  • 1
  • 2