ProgrammersitP

[Teddy]

My first university-level programming course (where we did functional programming), we had to be insanely meticulous with documentation, writing function specifications that usually were 2-3 times longer than the functions themselves for each and every function, no matter how insignificant or obvious nature. In the beginning I hated it, but toward the end, my views changed and I started to like the strict format. Except for writing the mandatory examples. Those were always a pain.

In my current course, however, we get specifications supposed to mimic those you get in the working life, i.e. ambiguous, missleading and possibly erroneous. I can't say that I like it, but hey, I suppose I'd better get used to it. And imperative/object-oriented programs aren't quite as easy to specify as functional ones...

Should still do some proper documentation of my own hobby projects. Especially since I have a tendency to drop them for several months before picking them up again...

[Capt Spanner]

My first university-level programming course (where we did functional programming), we had to be insanely meticulous with documentation, writing function specifications that usually were 2-3 times longer than the functions themselves for each and every function, no matter how insignificant or obvious nature. In the beginning I hated it, but toward the end, my views changed and I started to like the strict format.

I'm of the school of thought that says by reading through a list of functions that make up a thing it should be obvious what it's doing without comments. The rationale for this is that the code may get changed, but leave the comments, which become out of date. (I know I've confused myself on my own projects with this...)

As an example:

float getCylinderVolume(Cylinder cylinder) {
    return cylinder.height * getCircleArea(cylinder.circle);
}

float getCircleArea(Circle circle) {
    return pi * circle.radius * circle.radius;
}

I suggest that the above is clearly understandable without comments, and furthermore, if you were to see "getCylinderVolume( pump[3] );" somewhere in the code you would have no problem figuring out what it does.

So why take up valuable screenspace and brain-cycles with comments that don't add anything?

This is how I got good marks with very few comments in my projects.

[factotum]

That's self-documenting code, and it works to a degree. I still like to leave comments in my code so I remember myself what it's doing without having to figure it out from first principles, though!

[Teddy]

I'm of the school of thought that says by reading through a list of functions that make up a thing it should be obvious what it's doing without comments. The rationale for this is that the code may get changed, but leave the comments, which become out of date. (I know I've confused myself on my own projects with this...)

[...]

I suggest that the above is clearly understandable without comments, and furthermore, if you were to see "getCylinderVolume( pump[3] );" somewhere in the code you would have no problem figuring out what it does.

So why take up valuable screenspace and brain-cycles with comments that don't add anything?

This is how I got good marks with very few comments in my projects.

The problem is that the more complicated the function, the longer the name will have to be to explain what it actually does. Especially in functional programming where not only do you write new functions at an alarming rate, but where the standard method for repetition is recursion as well.

For example, take the function that takes a list and returns the list (or rather, an identical copy of the list) in reversed order. Naming it is a trivial task, anyone can figure out what reverseList does. But recursive functions are terrible to the stack if you can't make them tail recursive. The arguments for reverseList doesn't allow for tail recursion (or recursion at all, for that matter), however, so you have to write a helper function that takes two lists and prepend the first in reversed order to the second, but what would you name that one? reverseListAndPrependToList? It's too long! reversePrependList? Decidedly unclear name, I wouldn't want to guess what this function does!

And that was only a simple example. What would you call the function that takes a function, a value and a list and calls the argument function with the element at the front of the list and the argument function called with the next element in the list and so on until you reach the function call with the last element in the list, where you instead use the argument value as an argument instead of calling the argument function yet another time? It took me six lines to describe, and I'm pretty sure it's completely illegible anyway.

[Capt Spanner]

The problem is that the more complicated the function, the longer the name will have to be to explain what it actually does. Especially in functional programming where not only do you write new functions at an alarming rate, but where the standard method for repetition is recursion as well.

If a function is getting complicated, break it down into multiple, simple functions.

For example, take the function that takes a list and returns the list (or rather, an identical copy of the list) in reversed order. Naming it is a trivial task, anyone can figure out what reverseList does. But recursive functions are terrible to the stack if you can't make them tail recursive. The arguments for reverseList doesn't allow for tail recursion (or recursion at all, for that matter), however, so you have to write a helper function that takes two lists and prepend the first in reversed order to the second, but what would you name that one? reverseListAndPrependToList? It's too long! reversePrependList? Decidedly unclear name, I wouldn't want to guess what this function does!

LIST reverseList(LIST list) {
    if( list.size() == 0 )
        return list;
    LIST returnedList;
    addToBackOfList( returnedList, getItem( list, 0 ) );
    removeItem( list, 0 );
    return concatenate( returnedList, reverseList( list ) );
}

No confusingly named functions there.

And that was only a simple example. What would you call the function that takes a function, a value and a list and calls the argument function with the element at the front of the list and the argument function called with the next element in the list and so on until you reach the function call with the last element in the list, where you instead use the argument value as an argument instead of calling the argument function yet another time? It took me six lines to describe, and I'm pretty sure it's completely illegible anyway.

I'd use something based on "for_each" and describe the exact thing in problem space rather than solution space.

[CreganTur]

• Where are you and what are you doing in terms of programming? Employment, education or in your spare time?
  
  I'm web master and lead (read: only) programmer/applications designer for an internal website for a major financial institution.
  I'm completely self taught and have been programming for about 5 years now.
  
• What language or languages are you using primarily at the moment? What's your favourite, and why?
  ASP.NET is primary with C# and JQuery taking care of logic and scripting.
  C# is my favorite by far.
  I LOATHE pure Java. Can't stand how it handles objects.
  
• Where do you hope to go with your programming? Any plans for the future, or just waiting to see if anything of interest comes along?
  No real plans except hoping to one day quit my job and be a full time novelist.
  
• Any projects, personal or otherwise, you're in the middle of? Anything you're really focused on?
  My only personal project is an on-again-off-again project I'vee been working on for a while: a DM's toolbox that helps me track different things when I'm running a campaign.
  The first version was an initiative and damage tracker for the Dragon Age RPG. I really need to rewrite it for the Pathfinder game I'm starting tonight...
  
• What environment do you work/prefer to work in? Netbeans/Eclipse/Command line and a text editor?
  Visual Studio 2010 is my preferred environment- the ability to drag a tab out of the shell and onto a different monitor is inspired. Too bad most of what I work on is still stuck in VS 2008.
  
• Any problems that are driving you mad? A piece of code not compiling right, or being off by one, or one little syntax error in a sea of code? Not quite grasping the logic of a particular piece of code?
  The finer points of wbsite and server development escape me. Since I'm self taught, I know my code really well, but I don't have a broader view of things that most people who went to college for this have.

[Teddy]

If a function is getting complicated, break it down into multiple, simple functions.
[...]
No confusingly named functions there.

The problem is that your code is imperative, not functional. Or at least not optimised functional. To give the code for the helper function in SML code:

fun reverse' ([], aList) = aList
  | reverse' (rElem :: rList, aList) = reverse' (rList, rElem :: aList);

Extremely simple code (apart from the syntax, which might look a bit perplexing to those who don't know the language), but not self-documenting, and I've got the distinct feeling that self-documentation comes at the expense of optimisation...

I'd use something based on "for_each" and describe the exact thing in problem space rather than solution space.

Once again, to write the optimised function in SML:

fun foldr aFun aVal [aElem] = aFun(aElem, aVal)
  | foldr aFun aVal aElem :: aList = aFun(aElem, foldr aFun aVal aList)

This is one of those functions that entire lectures are devoted to explain (because it's riddiculously useful), and it's still but a library function. You can make it work, but the time you'd devote to make it obvious is probably no less than the time it'd take to write a standardised function specification in the first place.

Also, two final issues with only relying on self-documenting code: 1. everyone else is completely at mercy of your own idea of self-documentation (either is everything obvious at the moment of writing, or you haven't got any idea of what you're doing in the first place), and 2. it doesn't work with encapsulation.

[Wookieetank]

Maybe its just me, but python has me spoiled on reversing lists:

list = [thing1, thing2, thing3, etc]
list.reverse()

[Teddy]

Maybe its just me, but python has me spoiled on reversing lists:

[...]

Nah, it's one of the most common library functions for one of the most common data structures. Name any programming language with a mediocre standard library or better, and I'd bet you that there exists a function for reversing lists in it. I just needed an example to work with.

[Wookieetank]

Nah, it's one of the most common library functions for one of the most common data structures. Name any programming language with a mediocre standard library or better, and I'd bet you that there exists a function for reversing lists in it. I just needed an example to work with.

Fair enough.

[pendell]

I'm of the school of thought that says by reading through a list of functions that make up a thing it should be obvious what it's doing without comments. The rationale for this is that the code may get changed, but leave the comments, which become out of date. (I know I've confused myself on my own projects with this...)

As an example:

float getCylinderVolume(Cylinder cylinder) {
    return cylinder.height * getCircleArea(cylinder.circle);
}

float getCircleArea(Circle circle) {
    return pi * circle.radius * circle.radius;
}

First question: What units are we using? To what precision?

That's frequently the issue I run into when reusing other people's homebuilt functions. I may know that, say, I want the time of sale. I see there's a function that returns DateOfSale. So: Is that a Java Date? Or is it an integer representing milliseconds? seconds? Something else?

I've reverse-engineered a LOT of legacy code written by people who thought "the code should be clear by itself without the need for comments and documentation" and the experience can be compared to being stabbed repeatedly in the eyes with white-hot needles. It's been my experience that "self-documenting" code works well on short lab projects, but when you're dealing with tens of thousands or hundreds of thousands of lines of code which has mutated over the course of several years, the code quickly becomes illegible. Say hello to the big ball of mud .


This is doubly so because , in my experience, what is "clear and obvious" to one person is not at all to someone else.

I suggest that the above is clearly understandable without comments, and furthermore, if you were to see "getCylinderVolume( pump[3] );" somewhere in the code you would have no problem figuring out what it does.

In theory, that sounds good. In practice, what if getCylinderVolume() is overridden by multiple other subclasses? And what if getCylinderVolume() is obsolete code and the programmers have been using getCylVol() for the past year? Seen it happen.

So why take up valuable screenspace and brain-cycles with comments that don't add anything?

I'm not going to argue that most early CS courses take things to the opposite extreme of tacking on layer upon layer of wedding cake comments which are a burden to maintain and usually unhelpful. But I've also been on the receiving end of programmers (most) who don't believe in documentation at all.

I believe there is a happy medium, and that medium is best encompassed with the agile approach. You don't want fifty lines of comments for even three-line functions. I typically write up a one-paragraph doc describing the module or class and 2 or 3 sentences describing individual methods if necessary. I can do this because I've got a lot of experience with reading other people's code and know what a maintainer needs to know.

So I think it best to strive for "just enough" documentation. Too much of it simply means people copy-paste doc templates without concern for any actual information, with the result that the code is full of decorative comment blocks of no use to anyone. Too little of it means that the code is incomprehensible. So I recommend one paragraph per class with an optional one or two sentences per method -- so long as the method is trivial.

For a non-trivial method, such as the one I currently write to calculate sales tax, the algorithm should be written out. It is a complicated algorithm and not easily readable, since different states have different sales taxes, different products are taxed at different rates, and some states have multiple sales taxes while others do not. Europe includes sales tax in the selling price but the US does not.

I could go on, but the code is extremely hard to read, even for me, the person who wrote it. So the algorithm must be written out with mathematical equations and English comments. But there's no need to keep this algorithm description in-line : An article on the project wiki will do just as well.

I hope you see what I'm getting at: No comments is bad, but comments as taught in intro CS are even worse because they typically result in useless copy-pasted comment blocks of no utility. So the trick is to put away only as much information as you absolutely need to make life easier on the maintainers. It's something agile does well, and it gets easier with experience.

Respectfully,

Brian P.

[Balain]

I am totally stuck on the current assignment in computer science. Normally I can get it 80% working in the first day but not this time. Using python3 our program is to read a text file to make a dictionary(at least a dictionary is highly recommended so we can us keys like 'sun' instead of an index ), then use recursive functions to create output to be piped to a second program. the second program will draw a representation of the solar system.

the input file looks like:

Root Object: Sun

Object: Sun
satellites: Mercury,Venus,Earth,Mars,.....
Radius: 208937878
Orbital Radius: 0

Object: Moon
Orbital Radius: 25235235
Radius: 343442
period: 27.33532

Object: Earth
Orbital Radius: 32353523
period: 365.67
Radius: 532523
Satellites: Moon

There is no order to the listing of planets and moons.

I was thinking of creating a nested dictionary like

s={'sun':{'earth':{'moon':{'radius':3242,'orbit':372384,'period':35235},{'radius':343234..........}}}

the idea was I could call s['sun']['earth']['moon'] I haven't been able to get the input into a dictionary like that yet though.

Then I thought of using named tuples but that wasn't getting me anywhere either.

Anyone have any ideas on where to start better than I have had?

[factotum]

I'm not at all familiar with python, but what you need is some sort of hierarchical data structure--I doubt a standard array would fit that bill, you might have to hand-roll something.

[Teddy]

I don't know enough Python to give you any code, but I suggest you create an object to represent a celestial body, and then let it hold the body's satellites as a list of celestial bodies together with any other information you have of the body (radius, orbital radius, period, a string for easy searching...).

This way, you'll create a tree of celestial bodies with the sun as the root, the planets as intermediate branches and the moons as leaves (you can even give the moons satellites if you feel like it). Trees are easy to merge, so you can create a new tree for each body which you don't know where it goes (take the Moon, for example), and insert at the correct place later. On top of that, trees work very well with recursive functions, which is an added bonus for you.

[shawnhcorey]

I don't know enough about Python to get the nomenclature correct but in my favourite language, Perl, this is how I'd do it:

#!/usr/bin/env perl

use 5.010;
use strict;
use warnings;

# --------------------------------------
use Data::Dumper;

# Make Data::Dumper pretty
$Data::Dumper::Sortkeys = 1;
$Data::Dumper::Indent   = 1;

# Set maximum depth for Data::Dumper, zero means unlimited
local $Data::Dumper::Maxdepth = 0;

# --------------------------------------


my %solar = ();

my $object = '';
while( <DATA> ){
  chomp;
  next unless /:/;

  my ( $tag, $value ) = split /\s*:\s*/, $_, 2;
  $tag = lc( $tag );

  if( $tag eq 'object' ){
    $object = $value;
  }

  if( $tag eq 'satellites' ){
    $value = [ split /\s*,\s*/, $value ];
    for my $sat ( @$value ){
      $solar{$sat}{orbits} = $object;
    }
  }

  $solar{$object}{$tag} = $value;
}

print Dumper \%solar;

__DATA__

Object: Sun
satellites: Mercury,Venus,Earth,Mars,.....
Radius: 208937878
Orbital Radius: 0

Object: Moon
Orbital Radius: 25235235
Radius: 343442
period: 27.33532

Object: Earth
Orbital Radius: 32353523
period: 365.67
Radius: 532523
Satellites: Moon

It gives the result:

$VAR1 = {
  '.....' => {
    'orbits' => 'Sun'
  },
  'Earth' => {
    'object' => 'Earth',
    'orbital radius' => '32353523',
    'orbits' => 'Sun',
    'period' => '365.67',
    'radius' => '532523',
    'satellites' => [
      'Moon'
    ]
  },
  'Mars' => {
    'orbits' => 'Sun'
  },
  'Mercury' => {
    'orbits' => 'Sun'
  },
  'Moon' => {
    'object' => 'Moon',
    'orbital radius' => '25235235',
    'orbits' => 'Earth',
    'period' => '27.33532',
    'radius' => '343442'
  },
  'Sun' => {
    'object' => 'Sun',
    'orbital radius' => '0',
    'radius' => '208937878',
    'satellites' => [
      'Mercury',
      'Venus',
      'Earth',
      'Mars',
      '.....'
    ]
  },
  'Venus' => {
    'orbits' => 'Sun'
  }
};

I use an associative list to store each object and its data. Its satellites as stored as an anonymous array. I also added code to include the object each one orbits.

[Neftren]

Here's a quickie Python (2.7) solution. Depending on your assignment, there's probably a more clever way of handling this, but I'll leave that for you to figure out (small hint: regular expressions and string splitting). I'm not sure where the recursion bit fits in though.

# Planet Class
class Planet(): 
	name = ''
	satellites = {}
	radius = 0
	orbit = 0
	period = 0

# Program Data Structures
solar = Planet()
system = []

# Open and Parse the Input File
input = open('input.txt')
for data in input:

	# Linebreak Triggers New Stellar Object
	if data[0:] == '\n' and solar.name != '': 
		system.append(solar)
		solar = Planet()

	# Parse Search Queries by Substring for Object Data	
	elif data[:6].lower() == "object": solar.name = data[8:-1]
	elif data[:14].lower() == "orbital radius": solar.orbit = data[16:-1]	
	elif data[:10].lower() == "satellites": solar.satellites = data[12:-1]
	elif data[:6].lower() == "radius": solar.radius = data[8:-1]
	elif data[:6].lower() == "period": solar.period = data[8:-1]
	
system.append(solar)	# Append the Last Stellar Body
input.close()			# Close the Input File

# Iterate and Print Object Data
for i in system:
	print "Object: " + str(i.name)
	print "Satellites: " + str(i.satellites)
	print "Radius: " + str(i.radius)
	print "Orbit: " + str(i.orbit)
	print "Period: " + str(i.period)
	print "\n"

Spoiler

Show

You'll have to make modifications depending on how your input/output needs to be structured.

[Balain]

Cool, Thanks for all the help guys

[TSGames]

Speaking of Python, I just got it up and running on my Android device. I can now program in python and compile into an APK ob the device. I'm pretty stoked about it. =D

It also has the bonus feature (unwanted side effect) of allowing me to do the same with Java programs.

[Lord Loss]

Me and my friend were thinking of creating a self-improving program. We were wondering just how insanely difficult this would be. I have little knowledge of computer programming, and he's studied it for a year in school + some more out of school (we're in our last year of highschool). The idea would be to create a program that completes a simple task, then have it create a slightly modified version of its own code, then running most versions of the program. Whichever achieves the correct result the fastest would be kept, whilst the other would be discarded.

Thoughts? Advice?

[shawnhcorey]

See genetic programming.

[Ashtar]

You could say that the current javascript engines in browsers fit that criteria for "self-improving", since as they execute javascript code, they optimize it and use the result immediately. For example, V8 in Google chrome.

So it is possible to do it, mostly the self-improvement comes from compilation techniques: code branch prediction, dead variable elimination, ...

In certain cases, a compiler (Emscripten) can self-improve by compiling itself again, a recent example was highlighted on slashdot the other day.

[Gryffon]

Speaking of Python, I just got it up and running on my Android device. I can now program in python and compile into an APK ob the device. I'm pretty stoked about it. =D

It also has the bonus feature (unwanted side effect) of allowing me to do the same with Java programs.

Do you have a link to a good resource for this? I'd be interesting in doing some Python for Android.

[akma]

Speaking of Python, I just got it up and running on my Android device. I can now program in python and compile into an APK ob the device. I'm pretty stoked about it. =D

It also has the bonus feature (unwanted side effect) of allowing me to do the same with Java programs.

What program did you use? Is it any good?
(I don`t know Python, but I know java)

*self improving software*

I don`t know anything about the topic, but I think that you would have to be extremly carefull not to create a very buggy program, as the consequences would be very hard to predict.

[Balain]

solar system assignment again in python3. I started going with a the planet class , but talking with the TA that marks it, I would lose marks because the assignment says I should use a dictionary. So I got it creating my dictionary okay, which ends up looking like:

solar=
{
'root': Sun

'Sun': {'Satellites': ['Mercury', 'Venus', 'Earth'......], 'r':# , 'or': 0.0}

'Earth': {'Satellites': ['Moon'], 'r':# , 'or':#, 'p':#}

'Moon': {'r':#, 'or':#, 'p':#}

}

The radius('r') and orbital radius('or') are scaled to fit the screen resolution we have.

We pipe the output of our program to another program that will draw the solar system. We should use a recursive function to draw the sun,planets, moons, commits, etc. Some objects maybe listed as a satellite, but not exists as a dictionary entry.

I think I'm missing a logic step somewhere. My small sample with just the sun, earth moon prints the sun the earth orbit and earth but no moon. My large sample seems to print all the objects around the sun with their orbits and some of the moons (Jupiter's moons for sure). I'm super tired so I'm sorry if I'm missing something real stupid.

Here is the function:

#x,y are centre of screen
#solar is the dictionary
def draw_system(x,y,solar): 

     #draw the sun/planet/moon
     
     print('fillcircle', x,y,solar[solar['root']]['r'])
     print('text', solar['root'],x+solar[solar['root']]['r'],y+solar[solar['root']]['r'])

     #if the root object has satellites draw orbits
     
     if 'Satellites' in solar[solar['root']]:

          for s in solar[solar['root']]['Satellites']:

                #some objects in satellite list may not exists in dictionary
                #if it does print the orbit around root object
                
                if s in solar:
                print('circle', x,y,solar[s]['or'])

         for s in solar[solar['root']]['Satellites']:

         #if the satellite exists in the dictionary change 
         #the root in dictionary to new root
         
                if s in solar:
                    solar['root']=s
                
                    #call function with new x,y and dictionary with new root
                
                     draw_system(x,y+solar[s]['or'],solar)

and yes for now the x co-ordinate isn't changing I don't have the loops set up to draw the rotations I just want to make sure everything is drawing to the correct starting spot first.

[Teddy]

Something looks amiss with the for loop toward the end. The if statement, which I assume is supposed to be inside the loop, isn't indented, and if I remember what little I know of Python correctly, won't that mean that it's executed outside the loop?

Even if this is the case, I fail to see how this would cause the bugs you're experiencing (given, an undefined behaviour can do the wierdest things). Do you have access to a debugger with which you can step through the code and find out hwere the bugs appear?

[Balain]

Sorry the indenting wasn't like that in my code, it's how I copy and pasted it into here. I edited my last post so it looks better.

So far I have been doing this old school and just using vi. Although I have been thinking of downloading eclipse.


Well it's a new day and classes are done and the due date has been extended by 32 hours so hopefully I get it solved this afternoon.

OKay the problem wasn't with that function as far as I can tell. The problem is some of the moon have an extra space in the key so they get missed. back to creating the dictionary correctly.

[akma]

I have a problam with regular expressions in Java.
The program gets a string representing a mathmatical formula (a+b-3, for exemple), then you put values for the variables (possible 2 for a and 4 for b), and a method in the class returns the result (in this exemple, 3). I had a version that crashed in certain conditions due to bad design, so I commented out everything and started again.

After doing some modifications to the formula (converting from ab to a*b), I try to isolate the oparaters using String.split("[a-zA-Z0-9]"). This returns a String array, which always contains empty strings. I can bypass that, but I rather know why I get empty strings, and how to avoid it in the future.

[Balain]

Never mind I figured out my problem walking to the store lol

Incase any one actually cared what my problem was I spoiled it

Spoiler

Show

one more question about my assignment.
I have it working but would like to change the labels to be printed along
the side with a line pointing to each object as it moves.
This is in python3

so I have the following functions:

def draw_label(x,y,name,i):
     #print commands to draw labels in quickdraw window
     
      #print name along the left side of the quickdraw window 
      # and i*50 pixels from the top of the quickdraw window
      print('text' name, 700,i*50)

      #print line from the name to the centre of the object
      print('line' , 700,i*50, x,y)

(the next is very similar to the on in my previous post but I will shorten it
to some pseudo code here)

def draw_system(x,y,solar,t,i=0): #if i has no value set it to 0

    #do a bunch of calculations to x and y
    x = x*trig functions
    y = y* trig functions

    i = i +1
    #print the object to quick draw
    print('fillcircle', x,y, radius)
    
    #call the draw label function
    draw_label(x,y,object name,i)

    #some loops to draw orbits
     for loop
         do stuff

     for loop  #loop to get next object to be printed
            print(stuff)
            solar[rootobject]=[next root object]
            #recursive function call
            draw_system(x,y,solar,t,i)  #should be i+=1

When I use my small sample (Sun, earth, moon)it prints the solar
system okay and the labels seem to be okay

when I use my large sample it prints the solar system okay the sun label is
okay but further down there is a bunch of labels printed on top of each
other and further down another mess of labels.


Example:

Sun


jumbled mess1


jumbled mess2

I can't make anything out in each jumbled mess but my guess is
the first is planet names and second is moon names.
What am I missing to get each name printed 50pixels from each other?

[Balain]

I'm working on my last assignment in python3. and running into an index out of range error, and I'm not seeing why.

[factotum]

Sounds like a common or garden off-by-one error. In C, for example, array bounds start at 0, so it's a very common mistake for someone to declare an array with 8 elements and then try to access an element numbered 8, whereas the elements are actually 0 to 7. (Worse still, in C the compiler will usually let you get away with it, so you'll be reading or writing whatever happens to be in memory just beyond the end of your array!). Is Python similar?