[Ns-developers] About tags and how they are documented.

[Tommaso Pecorella]

Hi all,

following the discussion in Bug 1111 (https://www.nsnam.org/bugzilla/show_bug.cgi?id=1111), I have a little issue.

Tags (PacketTags, ByteTags and so on) are becoming more and more popular to attach infos to data passed around in ns-3.

Now, this is very handy and it's not at all a "bad" habit, however it's becoming more and more important to be able to document them.

The documentation need is twofold:
1) define a proper "do and do not" policy about tags, and
2) document the tags that are currently being used so users and developers DO remember what they are used for and what infos are there.

The point is: a tag is damn useful to carry cross-layer data, however it's too easy to use them as hidden function arguments. There is a concrete possibility that the developers will start to add tags just to avoid to have to change a poorly designed API. And that's not good, its a damn bad programming practice.
If tags will start to be used in a "bad" way, soon we'll have code that is totally unreadable and unmaintainable.

So, my suggestion is: write a "best practice for tags use" (easy to do) and find a way to put in the doxygen:
1) what's inside a tag
2) who is creating it (class and functions)
3) who is *removing* it <- this is trickier.

Comments ?


Cheers,

Tommaso


--------------------------------------------------------------

The nice thing about standards is that there are so many to choose from.
And if you really don't like all the standards you just have to wait another year until the one arises you are looking for.
-- A. Tanenbaum, "Introduction to Computer Networks"

--------------------------------------------------------------

Tommaso Pecorella - Ph.D.

Assistant professor
Dpt. Elettronica e Telecomunicazioni
Università di Firenze

CNIT - Università di Firenze Unit

via di S. Marta 3
50139, Firenze
ITALY

email: tommaso.pecorella at unifi.it
       tommaso.pecorella at cnit.it

phone : +39-055-4796412
mobile: +39-320-4379803
fax   : +39-055-494569