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)
[download]

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;
}
[download]

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;
}
[download]

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.

---

---

Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!

Titles consisting of a single word are discouraged, and in most cases are disallowed outright.

Read Where should I post X? if you're not absolutely sure you're posting in the right place.

Please read these before you post! —

• How do I compose an effective node title?
• How do I post a question effectively?
• Markup in the Monastery

Posts may use any of the Perl Monks Approved HTML tags:

a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr

You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)

	For:		Use:
	&		&
	<		&lt;
	>		&gt;
	[		&#91;
	]		&#93;

Link using PerlMonks shortcuts! What shortcuts can I use for linking?

See Writeup Formatting Tips and other pages linked from there for more info.