Where should “conversion” functions be placed?

Question

I have a type Bound as a sort of "alias" for an array of three numbers (working in TypeScript with: type Bound = [number, number, number]). I did this basically to help readability by specifying in the name what the array is used for. However, sometimes in my app I need to convert a number to a Bound and vice versa (for example 99 would translate to [0, 9, 9]). The code for this is fairly simple, but I'm wondering where would I place such a function? There seems to be no agreed-upon place to put conversion functions.

That is my specific problem, but the general question is there: Where should functions that convert types be placed?

Answer 1

This is a matter of convention and not an absolute rule, but in my programming experience, helper functions should be at the top of the file, because they will be used later and so they are a prerequisite to understand the body.

If a programmer wants to skip directly at a function that uses a helper, but didn't read the body of your helper, he will also be able to jump back to its definition because chances are he would have seen it defined in the top when scrolling down (and/or is aware of the same convention).

Answer 2

I'd take Robert C. Martin's advice on this one and make your code read like a newspaper article as he explains in his book Clean Code.

Think of a well-written newspaper article. You read it vertically. At the top you expect a headline that will tell you what the story is about and allows you to decide whether it is something you want to read. The first paragraph gives you a synopsis of the whole story, hiding all the details while giving you the broad-brush concepts. As you continue downward, the details increase until you have all the dates, names, quotes, claims, and other minutia.

Assume that someone is reading your code from top to bottom and when you call a function, assure that that function is defined directly below it. If your function is used in many different places, place it below the first call to it.

Answer 3

If the language permits it, I would place it on the object it operates on.

For example, you asks an Integer to convert itself into a Bound, so the conversion function takes place in the integer object.

The same goes for Bound to Integer but this time, on the Bound object.

Answer 4

In general, code should be written as it is intended to be read. Put your functions in the order that makes the code easiest for another programmer to understand them. That often means that the functions that get invoked first, such as main() and other high-level functions, should be early in the source file.