Jump to content


Photo
- - - - -

The Official Programming Tips Thread


  • Please log in to reply
6 replies to this topic

#1 ydoaPs

ydoaPs

    The Oncoming Storm

  • Moderators
  • 10,501 posts
  • LocationLocal Group

Posted 29 September 2016 - 03:41 PM

I noticed that a lot of the programming questions here, while phrased in terms of coding in specific languages, are actually rooted in a broader context of programming itself. People are having problem with the ideas behind programming in general. If we help people with algorithm building, the language-specific syntax falls into place.

So, this thread is for tips on programming in general. This isn't about programming in python or programming in java. This is about the fundamental heart of what one needs to do. If anything, it's tips on how to code in PseudocodeTM.

I'll start:

One of the biggest thing about programming is being able to break a problem down into chunks and then break those subproblems down. Keep doing that until you get a picture of what specifically you need to do to accomplish each major step. So, if your program needs to do things in three big steps, start even lower than pseudocode; start with a list.

Step 1
Step 2
Step 3

Then, take each of those steps and do the same thing.

Step 1:

Step 1a

Step 1b

Step 1c

Step 2:

Step 2a

Step 2b

Step 2c

Step 3:

Step 3a

Step 3b

Step 3c



You may or may not notice the indentation. That brings up my second tip.

Use indentation, called "whitespace", in your programs and even pseudocode. Some languages require you to have whitespace indentation (like python and the never ending tabs v spaces war), but many do not. It is still good practice for writing though. Most languages have interpreters or compilers that ignore anything about whitespace other than whether there is at least one space between two letters, so it won't hurt the program but it will help you. Writing, or at least planning, with whitespace keeps ideas organized. Look at the example in the previous tip. You see each substep, and it's clear where in the logic that it belongs. It makes code easier to read and understand, even if it's not required.

Speaking of readability and understanding, that's where my last two tips come in.

Make good names. Names like "MyFunction" or MY_CONSTANT are bad names. They don't tell you what the function is doing or what the constant is for. Make names descriptive, and your code will be easier to understand and easier to read. Rename (or "refactor") if you need to. Many programming environments will even let you replace all instances of one name with instances of the new name, so it won't even be a long tedious thing. Renaming, if giving a new name, is a good thing. It promotes clarity.

Comment everywhere. Comment to the point that you think you're overcommenting, and then comment some more. Future you will likely have no idea what your code is doing, so leave good notes for future you to use to figure it out.

Your turn.
  • 1
"Our integrity sells for so little, but it is all we really have. It is the very last inch of us. But within that inch we are free."-Valerie(V for Vendetta)

"For small creatures such as we the vastness is bearable only through love and whiskey."-Carl Sagan[revised]
 
"The universe is under no obligation to us not to be absurd."

#2 Strange

Strange

    SuperNerd

  • Senior Members
  • 11,933 posts
  • Location珈琲店

Posted 29 September 2016 - 04:04 PM

Comment everywhere. Comment to the point that you think you're overcommenting, and then comment some more. Future you will likely have no idea what your code is doing, so leave good notes for future you to use to figure it out.

 

Make your comments descriptive and useful (e.g. don't comment a line that increments a counter with /* increment counter */, try something like /* keep track of the number of lines we have processed */). Imagine you are explaining your code to someone else (who isn't as smart as you) when writing comments.

 

Add comments at the start of each file saying what that file contains.

 

Add comments at the start of each function/procedure saying what the function does, what parameters it takes and what it returns. Add comments at each step in the function explaining what it is doing and why it is doing it that way - it is OK to document your design decisions in the comments. Otherwise, one day you might come back and think, "that seems an odd way of doing it; I think I'll simplify it .... Oh no! Why doesn't it work any more!?"

 

As well as using meaningful variable names, add comments to the declarations with more info (e.g. why it is that type /* We use a set rather than a list here to automatically remove duplicates, and we don't care about the ordering */)

 

If you "temporarily" comment out lines to try a different implementation then:

1. Add a comment explaining why those lines are commented out

2. Consider deleting them when you are happy with the new version

3. Start using a version control system!

 

Keep the comments up to date with the code; e.g. if a function is given an extra parameter, update the comments.


  • 1

#3 ydoaPs

ydoaPs

    The Oncoming Storm

  • Moderators
  • 10,501 posts
  • LocationLocal Group

Posted 29 September 2016 - 04:56 PM

Make your comments descriptive and useful (e.g. don't comment a line that increments a counter with /* increment counter */, try something like /* keep track of the number of lines we have processed */). Imagine you are explaining your code to someone else (who isn't as smart as you) when writing comments.
 
Add comments at the start of each file saying what that file contains.
 
Add comments at the start of each function/procedure saying what the function does, what parameters it takes and what it returns. Add comments at each step in the function explaining what it is doing and why it is doing it that way - it is OK to document your design decisions in the comments. Otherwise, one day you might come back and think, "that seems an odd way of doing it; I think I'll simplify it .... Oh no! Why doesn't it work any more!?"
 
As well as using meaningful variable names, add comments to the declarations with more info (e.g. why it is that type /* We use a set rather than a list here to automatically remove duplicates, and we don't care about the ordering */)
 
If you "temporarily" comment out lines to try a different implementation then:
1. Add a comment explaining why those lines are commented out
2. Consider deleting them when you are happy with the new version
3. Start using a version control system!
 
Keep the comments up to date with the code; e.g. if a function is given an extra parameter, update the comments.


A common analogy is to comment like you're explaining it to a rubber duck.
  • 0
"Our integrity sells for so little, but it is all we really have. It is the very last inch of us. But within that inch we are free."-Valerie(V for Vendetta)

"For small creatures such as we the vastness is bearable only through love and whiskey."-Carl Sagan[revised]
 
"The universe is under no obligation to us not to be absurd."

#4 timo

timo

    Scientist

  • Senior Members
  • 3,389 posts
  • LocationGermany

Posted 29 September 2016 - 08:34 PM

 

Make your comments descriptive and useful (e.g. don't comment a line that increments a counter with /* increment counter */, try something like /* keep track of the number of lines we have processed */). [...]

Or you call your counter variable "numberOfLinesProcessed" or "linesProcessed" and reconsider if you really need to comment the increment. In my experience, certain circles tend to dislike in-code commenting except for cases where something unexpected happens or a non-obvious choice has to be explained (and both case classes should be avoided). And in recent years I have come to adapt that way of programming. That said, "comment a lot, even in-code" is probably still a good advice for beginning programmers, who I assume are the target audience for this thread.

 

As for a tip I'd have: If in doubt, try it out. Simple examples: What values does a loop over "range(10)" cover? Is "x[1]" the first or the second element in an array x? What is the result of y = A*x, where A is a 2D-array/matrix and x is a 1D-array/vector? You can read the manual. But it takes time and you need to be certain that you understood it correctly. And once you leave language features and go to library-features you also have to implicitly assume that the library behaves according to its documentation (i.e. that it does not have a bug). Or you can just assume something and hope everything goes well. Or you can just try it out and discover the answer for yourself, which is often faster than reading manuals and produces less errors than just assuming some behaviour. And most importantly: It's the most fun variant.


Edited by timo, 29 September 2016 - 09:02 PM.

  • 0

"Ocean madness is no excuse for ocean rudeness" -- H.J. Farnsworth


#5 Sensei

Sensei

    Scientist

  • Senior Members
  • 3,097 posts

Posted 29 September 2016 - 10:41 PM

One of the biggest thing about programming is being able to break a problem down into chunks and then break those subproblems down. Keep doing that until you get a picture of what specifically you need to do to accomplish each major step. So, if your program needs to do things in three big steps, start even lower than pseudocode; start with a list.

 

The best is to start with activity diagrams, with arrows.

https://en.wikipedia...ctivity_diagram


  • 2

#6 ydoaPs

ydoaPs

    The Oncoming Storm

  • Moderators
  • 10,501 posts
  • LocationLocal Group

Posted 20 October 2016 - 04:48 PM

Learn some math. Even the really basic stuff can let you do really cool things. Many of the machine learning techniques aren't all that mathematically complicated. Neural networks, for examples, are little more than optimizing weighted averages of a step (or sigmoid or something like a sigmoid) function.
  • 0
"Our integrity sells for so little, but it is all we really have. It is the very last inch of us. But within that inch we are free."-Valerie(V for Vendetta)

"For small creatures such as we the vastness is bearable only through love and whiskey."-Carl Sagan[revised]
 
"The universe is under no obligation to us not to be absurd."

#7 Strange

Strange

    SuperNerd

  • Senior Members
  • 11,933 posts
  • Location珈琲店

Posted 20 October 2016 - 09:45 PM

I am exaggerating very slightly in this list. But not much.

  1. Write a specification.
  2. Get it reviewed.
  3. Then write a test plan based on the specification. 
  4. Get it reviewed.
  5. Then write the tests, based on the test plan.
  6. Get them reviewed.
  7. Correct the specification based on the errors this throws up.
  8. Write the documentation.
  9. Get it reviewed.
  10. Correct the specification and test plan based on the errors this throws up.
     
  11. Oh, yes. Implement the software. (Nearly forgot.)
  12. Correct the specification and test plan based on the errors the throws up.
     
  13. Run the test suite for each module and for the complete program.
    Fix any bugs and get the changes reviewed before committing them back to the repository.
    This should not be the longest part of the development process (but, sadly, for most people it is).

Edited by Strange, 20 October 2016 - 09:45 PM.

  • 0




0 user(s) are reading this topic

0 members, 0 guests, 0 anonymous users