|
There has been a fairly recent crusade against comments. Some claim code should be self-documenting and that comments are somehow evil.
You know what's documenting? Documentation... like comments.
Self-documenting? WTF? There's nearly zero code ever written that explains WHY it does what it does or WHY it was changed to do otherwise. I guess you can enforce tying commits to cards and chase down the commit that changed the code and then the card that brought that commit.
Alternatively, maybe a comment isn't such a bad thing.
Has nobody written a VS plugin to just turn all comments on/off?
Is it really just that developers hate documentation so much they'd rather claim their code does all the documentation for them? Because that's just how great their code is?
Do people not use XML comments so people get intellisense on what they are calling? Do they think making that block descriptive is some massive chore?
|
|
|
|
|
That crusade against comments has been going on for many years, where I have been.
The major exception is huge copyright/left comment blocks topping every source file and extensive comment blocks heading every function, repeating the function name, the the types and names of all parameters of the function declaration, only doing it in 10-20 lines instead of one, cluttered with typographic markup.
I have been heavily criticized for my habit of adding a lot of explanatory ("why") end-of-line comments - end-of-line because I like to see the entire function/method in a single screenful rather than three. I also have a habit of aligning the comments from col 80, so that they do not visually disturb the code itself - you look at the comments (only) if you wonder "why". A number of my critics also love to open three source file windows side by side, so narrow that they usually won't see my comments, which are outside of their windows 
|
|
|
|
|
|
Comment for yourself. Some devs will read them... some... if they are coherent and make sense to a different person. And then some devs refuse to take any initiative... so good luck with that.
Jeremy Falcon
|
|
|
|
|
I guess I should have provided context on what I mean as a comment. For as long as I've been writing code, I outgrew quickly code comments that say "increment the pointer" and other trivial stuff. I also like *limited* Hungarian notation: certain prefixes that over time just help me scan the code. Years ago, I picked up the habit that every pointer begins with a lower case p. Key was readability.
As for oxygen and other tools like that, they sometimes help understand the overall system (especially call trees) but development tools have made such advancements that most of the doc has been replaced by tool features (hovering over a variable for example). The best tool I've ever used is Understand from SciTools. Unfortunately, they moved from a perm. license model to monthly fees, pricing it out of my market.
Rather than what, I try to explain why the code does what it does. Example of the table of data - that's what and you can infer why. In my case, I have a piece of common code that runs on 4 different platforms. Thelatest platform has some issues to be worked around, and I found myself trying to explain why. It then occurred to me that I knew the product was reaching end of life, no one will likely read this, just comment in the SVN commit.
After reading all of the replies to my question, it might be wordier, but breaking up the code into 4 different methods (each supporting a specific device) is probably the cleaner approach.
Thanks for the insights.
Charlie Gilley
“They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759
Has never been more appropriate.
|
|
|
|
|
Sometime in the 1970s one of our users reported a problem entering a date for a future event. The code was not written by us, but we had the source, so I pulled up the code to see how it worked. I found this comment (PDP-10 assembler)
"Thirty days hath September, all the rest I can't remember, except February which never works anyway" There was no code to handle leap year! At least the comment helped us know we were in the right place. That isn't the worst comment I found in code from that source, but the worst would violate nsfw rules.
|
|
|
|
|
I like it!
Charlie Gilley
“They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759
Has never been more appropriate.
|
|
|
|
|
Most PC mainboards have various 'headers' (why are they called that?) for attaching I/O sockets on the back, LEDs on the front, internal fans etc. Micros such as Arduino have lots of them - super simple, naked pins, no shielding, no locking holding the plug in position. Sometimes the board has the male pins, sometimes it has the female receptacle. They are far less robust that the power connectors.
I believe that the distance between pins are 1/10", commonly in a single row, but two rows is not uncommon. The number of pins vary from 2 (or even 1) up to at least 36. The cross section is usually square, but is is always? Always the same size (pin thickness)? Always 1/10" apart?
I have tried to find out what these connectors are called, to learn about their specification. There must be some standard defining them. What is the name or number of that standard? Maybe there are several standards - I suspect that some of them have a pin distance smaller than 1/10". Sometimes, there is a lock and release on the plug (typically on fan connectors), but maybe that is a different standard? (Or several different ones - 'The good thing about standards' etc.
Can anyone provide the name of the connectors, so I can google for more complete information? Or possibly give me a link to more information about them: Physical dimensions/distances, pin shape/length, male/female usage, lock/release usage, acceptable voltages and current/power and so on.
|
|
|
|
|
Just to clarify. Are you talking about, for example, the GPIO pins on a Raspberry PI, which seem to be the same as the pins on old IDE Hard drives for Master/Slave/CS?
Keep Calm and Carry On
|
|
|
|
|
I never worked with Raspberry Pi, but looking at the top photo of Wikipedia: Raspberry Pi[^] looks like the male version of what I am thinking of.
Wikipedia: Arduino[^] shows a photo with 8 and 10 pin female connectors along the edges, and two groups of 2 by 3 male connectors. (I believe that even they seem to be made of 3 independent 2 pin connectors, the plastic at the bottom keep them at a standard distance so that a single 2 by 3 female connector would fit.)
The IDE, aka PATA, connectors I remember are quite robust, with a frame around the pins having a slot to ensure that the plug is not turned around and that it is pushed straight down. The plug is sturdy, usually attached to a flat cable making it even sturdier. The male pins are significantly shorter. The plug (female) sometimes has one hole covered, and wouldn't fit on the Raspberry Pi GPIO. I guess the PATA standard would define this connector.
I was thinking of the less robust ones such as those for making connections from the PC front panel LED/buttons to the mainboard, such as those shown on YouTube: Explaining PC Front Panel Connectors [^] (you don't have to play the video to see the photo of the plugs).
Is there a name/standard for these kinds of connectors?
If you look at Wikipedia: Computer Fan[^], next to the section 'Multiple purposes' ("A small blower fan ..."), you will see a fan connector that will fit onto a single-row header, but in a proper fan socket you can only insert it one way. Is this a different standard from the headers, and if so, what is it called?
|
|
|
|
|
Sorry to be negative, but whilst there are design standards for such connectors (indeed often called 'headers' when on devices) there are so many 'standards' for so many different kinds of connectors used in so many situations (eg soldered on a PCB, in-line in a cable, surface mount) not to mention for different purposes (eg RS232 - lots of different ways of wiring these even with a standard to follow), SCSI, USB (four 'standards for this in current use and rising), power (uncounted numbers of DC power plug connectors), video monitors (at least 8 that I know of) that all you can do is try to establish which ones you are connecting to and match that type.
Even then, some connectors are made for a particular manufacturer for a specialised purpose and will only connect to their 'headers' etc (eg early Apple iPhone)
Physical interconnections are still, after all these years, very much not standardised except for a small range of consumer products, and even these (eg USB - C) can vary depending on what uses they are intended for...
Sorry again!
|
|
|
|
|
|
That article is covering a lot of different header connectors. Sure, the ones I am thinking of are the ones first presented.
However, the article does not discuss the use of female vs. male pins, limits on current or voltage, details of dimensions etc. and does not refer to any standard or formal name. (It refers to "Berg connector", but that is not the kind of connector they are discussion, so it is rather misleading.)
Are computer manufacturers really using these connectors without them being formally defined in a standard? Are component manufacturers making these headers and sockets, selling them without any references to specifications of their properties?
|
|
|
|
|
in answer to your last para:
YES!
|
|
|
|
|
I don't think he's talking about Pi - but PC main boards.
Without getting into a long long long discussion, the reason "boards" are laid out the way they are is due to standards. Standards - a group of people that decide we shalt do it this way. There are many standards. The reason it's good to follow standards is to allow to sell your product.
Let's talk PC boards. They need to allow Intel and AMD to drop processors into them. What about PC cases? Well, the boards and the PC cases better agree. It goes on an on. List: CPU requirements, where to put the PCI, PCI Express, SATA connectors, agreed upon power connectors.
Industry groups got together to create consortiums so all progress.
Charlie Gilley
“They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759
Has never been more appropriate.
|
|
|
|
|
You see such headers (male) and sockets (female) both on PC main boards, Raspberry Pi, Arduiono and lots of other places.
As you say: There must be an agreement, for lots of things. That agreement is usually identified by a name or standard number, pointing to a defining document.
I was hoping to find a pointer to such a defining document for these headers.
E.g. Wikipedia: Pin header[^] refers to various header pitches and a couple pin cross sections - but from which document are are these values taken? What else is found in that document?
|
|
|
|
|
I have always found company's like RS / Farnell (Newark, Element 14)'s Web sites quite good if you look for Pin Headers they all the spec's you could want. Molex is a name for a family/ brand, also Pheonix is a another brand name (very resilant, green coloured!). As to voltage the data sheets can give better guidance than I (9 Volts is safe, 5 is normal). I have always kept to around 50mA, the Pheonix I have use for 4-20 system with no problem. Phoenix tend to have threaded bolt as attachment, Molex I have seen with threaded bolts and clips. For use figures have a look at 'mating cycles' (higher the better!)
|
|
|
|
|
Could you provide a link to those web sides with the specs?
It is easy to find 'hearsay', things that 'everyone knows that' so and so. (And essentially, I have known the connectors at that level for many years!)
Finding complete, hard specs is quite a bit more difficult!
|
|
|
|
|
I was surprised how tricky it was/is to find the info - iI believe the pin spacing is 2mm in each direction, and Farnell have info on a 20-pin, 2mm IDC receptacle: 89361-720LF Amphenol Communications Solutions, IDC Connector, IDC Receptacle, Female | Farnell UK[^]
The data sheet for that shows it is made by Amphenol, drawing number 83951, title '2.00 mm IDC'. It seems obvious that this must be an industry-agreed design (dimensions, at least), or nothing would fit together, but where the spec for such standards may be found is another matter.
|
|
|
|
|
Generally they are set by ISO International Standards Organisation. ISO has a standard for it, look for someone muttering 'ISO 909 part B' chances are they are Quality Inspectors panicing! 
|
|
|
|
|
|
|
Oh boy. As you would expect, there's lots of variables that come into play. The pin and plug have to meet the needs of the voltage and amperage that they will carry. Pin spacing will also be affected by the size of the traces and their spacing that the pins will attach to on the circuit board. Beyond that, it comes down to the preferences of the manufacturer.
|
|
|
|
|
The only "standards" for the most part are set by the specific manufacturer, for a specific product line. There literally thousands of product lines in current use, and tens of thousands more historic lines that are no longer made. As you can see here at a popular parts supplier in the US:
https://www.digikey.com/en/products/category/connectors-interconnects/20
there are over 5 million separate results searching for "connector". That is FAR from a comprehensive list. There are hard metric, hard English pin size/spacing's and a few that are "both" meaning close to an even mm dimension and an English dimension that is an even fraction of an inch. Sizes range from so tiny you cant see the individual pins to huge (for high power AC distribution for example), depending on application. By convention the headers on mother boards are .1" spacing (both ways if multiple rows). The shroud (with or without key slot) is optional and often omitted as a cost saving measure. these are a significant improvement over edge card connections, but still not exactly "safe". The pins are always square and "tinned (coated or plated with metals similar in appearance and possibly composition to solder)" or gold plated, which effects reliability, cost, and capability (voltage and current specs). The mating female connectors come in a variety of sizes, and internal construction in turn effecting cost and performance. MOST of an EE's job in the modern world is about selecting parts for availability, spec, cost, etc. EVERYTHING is tradeoffs: cost vs performance vs thermal management vs ease of use/manufacture etc. etc.
Every manufacturer thinks their products are superior - and maybe they are in some applications. Nothing works well everywhere. Some (like 0.1" pitch headers) are more common than others. Even in specialized applications like RF there are dozens of kinds in common use, all have their pluses and minuses. And a hundred more that are very uncommon and found only in certain applications or in certain countries products.
Using the latest technology to create tomorrows problems today.
|
|
|
|
|
I believe the connector variety you're looking for was originally manufactured by Dupont. They are called Dupont connectors these days.
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
