DrawLine args name confusion

Started by
11 comments, last by _the_phantom_ 10 years, 1 month ago

It may sound silly but this confuses me and is some case

for makes me feel a 'little unhappy' - I am never sure what names

to use in such case

DrawLine(int x1, int y1, int x2, int y2, unsigned color);

or maybe

DrawLine(int x0, int y0, int x1, int y1, unsigned color);

or maybe

DrawLine(int ax, int ay, int bx, int by, unsigned color);

or

DrawLine(int x, int y, int x_, int y_, unsigned color);

or what?

good naming makes code clearer and faster to work with,

so it is important

one thing i noticed one day is that namink like x0, y0, x1, y1

are somewhat logicaly wrong becouse logicaly it is (should be) more like

0.x 0.y 1.x 1.y [not x.0 y.0 x.1 y.1 ]

Advertisement

I prefer distinguishing the points with numbers, since you dont have two different unrelated data but two data that are essentially the same. Naming them using a and b would hide information, there would be no relation between them.

When you use numbers it is usually possible for the compiler to understand that there is a relation. This does not apply in your case but if you were to implement a more complicated system in C++ or similiar, you might use:

template<int dimensions>

drawLine(std::array<Vector<dimensions>> dimensions> points);

Here you tell the compiler that the points are members of the same set of data and as such should only be distinguished by integers/keys, not be separate symbols. This allows the code to be more general, so you can draw some 4D lines in the future. If you instead did

drawLine(point a, point b)

It would not be possible to generalize it as easily since the two points are not part of the same data.

This doesnt propably matter in C but at least its a tiny bit closer to being more generalized code if you distinguish the data that belongs together by 'anonymous' names like integers. So i suggest you use

drawLine(int x0, int y0, int x1, int y1, unsigned int color)

or

drawLine(Point p1, Point p2, Color color) if you were to make it more strict with the types

o3o

The conceptual template you want to build on top of is probably this:


/** Draws a line from point src to dst [inclusive/exclusive] of a specific color.
  *
  * (add notes about any shared state the function may be using, if any)
  * (specify how the function behaves if out of range points are given)
**/
void DrawLine(Point src, Point dst, Color color);

If you really must break up the two coordinates into two distinct parameters, then you can qualify then like srcX, dstY and so on. I don't think any of your suggestions are really self-documenting. (x1, y1) and (x2, y2) (or the zero-based equivalent) is what most people expect, as logically people expect to pass the starting point first and the end point afterwards, but there's nothing besides convention that explains what x1, y2, etc.. really stand for. (ax, ay) and (bx, by) is passable, and (x, y), (x_, y_) is straight-up ridiculous because the underscore conveys no information to the reader beyond "WTF".

“If I understand the standard right it is legal and safe to do this but the resulting value could be anything.”

one thing i noticed one day is that namink like x0, y0, x1, y1
are somewhat logicaly wrong becouse logicaly it is (should be) more like
0.x 0.y 1.x 1.y [not x.0 y.0 x.1 y.1 ]


I assume you never had formal mathematical education? Because writing x0 (the closest you can get to a subscripted index usually) is probably the most native and canonical way for a mathematician to deal with the issue.

The conceptual template you want to build on top of is probably this:


/** Draws a line from point src to dst [inclusive/exclusive] of a specific color.
  *
  * (add notes about any shared state the function may be using, if any)
  * (specify how the function behaves if out of range points are given)
**/
void DrawLine(Point src, Point dst, Color color);

If you really must break up the two coordinates into two distinct parameters, then you can qualify then like srcX, dstY and so on. I don't think any of your suggestions are really self-documenting. (x1, y1) and (x2, y2) (or the zero-based equivalent) is what most people expect, as logically people expect to pass the starting point first and the end point afterwards, but there's nothing besides convention that explains what x1, y2, etc.. really stand for. (ax, ay) and (bx, by) is passable, and (x, y), (x_, y_) is straight-up ridiculous because the underscore conveys no information to the reader beyond "WTF".

in mathematics people would often use x,y to x', y'

so this x_, y_ simulates in my opinion this (imo it is also not so bad it makes code looking clearer than x1, y1, x2, y2)

naming are hard part in programming

your proposition src dst is also not good if treated heavy -

becouse in line you do not get the source point and destination point, not sure if i realy even got a begin point and end point

(just two points - now im closer to use

DrawLine(int px, int py,int qx,int qy, color);

maybe

:U

I prefer distinguishing the points with numbers, since you dont have two different unrelated data but two data that are essentially the same. Naming them using a and b would hide information, there would be no relation between them.

When you use numbers it is usually possible for the compiler to understand that there is a relation. This does not apply in your case but if you were to implement a more complicated system in C++ or similiar, you might use:

template<int dimensions>

drawLine(std::array<Vector<dimensions>> dimensions> points);

Here you tell the compiler that the points are members of the same set of data and as such should only be distinguished by integers/keys, not be separate symbols. This allows the code to be more general, so you can draw some 4D lines in the future. If you instead did

drawLine(point a, point b)

It would not be possible to generalize it as easily since the two points are not part of the same data.

This doesnt propably matter in C but at least its a tiny bit closer to being more generalized code if you distinguish the data that belongs together by 'anonymous' names like integers. So i suggest you use

drawLine(int x0, int y0, int x1, int y1, unsigned int color)

or

drawLine(Point p1, Point p2, Color color) if you were to make it more strict with the types

I agree with this generalisation notices too in general,


in mathematics people would often use x,y to x', y'
so this x_, y_ simulates in my opinion this (imo it is also not so bad it makes code looking clearer than x1, y1, x2, y2)

naming are hard part in programming

your proposition src dst is also not good if treated heavy -
becouse in line you do not get the source point and destination point, not sure if i realy even got a begin point and end point
(just two points - now im closer to use

DrawLine(int px, int py,int qx,int qy, color);

maybe
:U

Well, if you go that way, the function is poorly named because a line has no beginning nor end. So when you say "draw a line" what you really mean is "draw a segment" (which does have a beginning and an end point). And I don't think using an underscore as an alternative for a prime (') character is idiomatic. Usually underscores are used as substitutes for whitespace.

“If I understand the standard right it is legal and safe to do this but the resulting value could be anything.”

one thing i noticed one day is that namink like x0, y0, x1, y1
are somewhat logicaly wrong becouse logicaly it is (should be) more like
0.x 0.y 1.x 1.y [not x.0 y.0 x.1 y.1 ]


I assume you never had formal mathematical education? Because writing x0 (the closest you can get to a subscripted index usually) is probably the most native and canonical way for a mathematician to deal with the issue.

I was studying physics but three years only, later skipped it

you know what I mean you are interested here in Ax, Ay, Az

Bx, By, Bz more than xA, yA, zA, xB, yB, zB, so

those x0, y0, z0, x1, y1, z1 are just sme kind of reversed


in mathematics people would often use x,y to x', y'
so this x_, y_ simulates in my opinion this (imo it is also not so bad it makes code looking clearer than x1, y1, x2, y2)

naming are hard part in programming

your proposition src dst is also not good if treated heavy -
becouse in line you do not get the source point and destination point, not sure if i realy even got a begin point and end point
(just two points - now im closer to use

DrawLine(int px, int py,int qx,int qy, color);

maybe
:U

Well, if you go that way, the function is poorly named because a line has no beginning nor end. So when you say "draw a line" what you really mean is "draw a segment" (which does have a beginning and an end point). And I don't think using an underscore as an alternative for a prime (') character is idiomatic. Usually underscores are used as substitutes for whitespace.

the problem is all the names here bring a little confusion imo

(and its just hard to decide)

(say three family names, if you treat each of those

example as a family

1)

DrawLine(int x0, int y0, int x1, int y1, unsigned color);

2)

DrawLine(int ax, int ay, int bx, int by, unsigned color);

3)

DrawLine(int x, int y, int x_, int y_, unsigned color);

maybe some other propositions (but prefereably assume that this must stay this form 4 ints separately)

You can think of

x0 y0 x1 y1

as if they were array indices

x[0] y[0] x[1] y[1]

But you have 2 arrays one for x values and one for y values.

If you want it the other way around you must have an array of points

Points[0].x

Points[1].y

But this changes data layout so you might want to make your choice based on what the optimal data layout is, not what looks the nicest.

o3o

This topic is closed to new replies.

Advertisement