http://www.perlmonks.org?node_id=864538


in reply to Re^2: Code Critique
in thread Code Critique

I am a big fan of design by comments, at least for relatively simple projects.

What this means is, start with an English (or whatever language makes sense to you) description of what the program should do. Keep it all very simple and high level. Don't go into great detail about formats and so forth at first.

# This program takes a list of foo data files # for each file it: # reads the file # sanitizes the data fields # converts the file to csv (name is based on foo file name)

Now you can write some code. Keep everything related to the current idea all on one screen of text. If it gets too long, wave your hands and invent a subroutine name.

# This program takes a list of foo data files my @foo_files = @ARGV; for my $foo_file (@foo_files) { save_foo_file_as_csv( $foo_file ); } sub save_foo_file_as_csv { my $foo_file = shift; my $csv_file = convert_foo_name_to_csv_name($foo_file); my $foo_data = read_foo_file( $foo_file ); $foo_data = sanitize_data( $foo_data ); write_as_csv( $csv_file, $foo_data ); return; }

Now, the top level of abstraction is done. Of course the code won't work yet. We've waved our hands an awful lot. We now need to implement each sub we invented to avoid having to think about the details of what we're doing.

Each sub is effectively its own little program. Repeat this process for each subroutine until they are all written. For example, we can be very concrete about how we convert a foo file name into a csv file name. No need for additional subs:

sub convert_foo_name_to_csv_name { my $name = shift; $name =~ s/(.foo)?$/.csv/c; return $name; }

Something like sanitize_data() may be more complex, and even need a good number of subs of its own.

Once you've fleshed out all the subs, your code will be done.

For existing code, work in reverse. Label things. Describe what is happening. Take big blocks of code and move them into a sub and replace them with descriptively named routines.


TGI says moo