Related
I have an OOM model with a few classes that will be transformed into C++ code.
I want certain sections (ie. custom #includes in .cpp files) to remain untouched when I re-generate the code from the model. However if I modify the model and generate the code again this defines & includes are lost.
Found nothing looking at the docs for macros or variables that may be of help.
Can anyone help?
In the Script tab of a class property sheet, there is a Imports subtab. Looking in the Object Language Definition, this attribute does not seem to be used anywhere.
I managed to use it by editing the Profile\Class\Templates\Source\includes_cpp template in the Language definition, adding %Imports% at the end.
After that, this Imports appears in the generated source:
#include "Class_2.h"
#include "Class_1.h"
MY INCLUDES
question is related to Using Doxygen with C, do you comment the function prototype or the definition? Or both? .
doxygen formatting makes the declaration and its comments from my .h file appear first, followed by the definition and its comments from my .c file. good.
alas, is there some parameter like \param[in] or \return[in] that I can use just before the .c definition for the html output to indicate visually "now I am describing implementation"? It could put a boldface on the left, or even change the color to set it off visually. The obvious \implements tag does not do this.
I looked at the generated doxygen html code, and there is no obvious css class to change. so I presumably should use a tag from http://www.doxygen.nl/manual/commands.html . what do others use?
One option, which is not ideal but does have the merit of simplicity, is to use the \note command.
Prefixing the paragraphs describing the implementation with \note will result in them showing in the output with a green'y-yellow sidebar. You could change the color in the CSS. Subsequent \note paragraphs will remain as separate paragraphs but have a single heading and sidebar.
The downside is that the section is headed Note:. This may or may not be acceptable for your needs.
You could use \xrefitem instead, which would allow you to change the text to Implementation:, but it, quite reasonably, also generates an entry on a separate cross-reference page - which is probably not desirable. There may be a way of disabling the cross-indexing, but there's nothing in the manual about it.
I assume you are generating a document that is for internal use only; some form of Technical Manual perhaps? In which case, the 'Note' option may be the quickest and simplest solution.
Edit: I've just found the \remark command. Essentially equivalent to \note without a sidebar, but the associated heading Remarks may suit your application better. Chances are you can add the sidebar in the CSS.
Ui:include and xhtml based tag (the one with source elt) seem to be much the same for me. Both allow to reuse piece of markup. But I believe there should be some reason for having each. Could somebody please briefly explain it? (I guess if I read full facelets tutorial I will learn it, but I have not time to do it now, so no links to lengthy docs please :)
They are quite similar. The difference is mainly syntactical.
After observing their usage for some time it seems the convention is that fragments that you use only in a single situation are candidates for ui:include, while fragments that you re-use more often and have a more independent semantic are candidates for a custom tag.
E.g.
A single view might have a form with three sections; personal data, work history, preferences. If the page becomes unwieldy, you can divide it into smaller parts. Each of the 3 sections could be moved to their own Facelet file and will then be ui-include'ed into the original file.
On the other hand, you might have a specific way to display on image on many views in your application. Maybe you draw a line around it, have some text beneath it etc. Instead of repeating this over and over again you can abstract this to its own Facelet file again. Although you could ui:include it, most people seem to prefer to create a tag here, so you can use e.g. <my:image src="..." /> on your Facelets. This just looks nicer (more compact, more inline with other components).
In the Facelets version that's bundled with JSF 2.0, simple tags can be replaced by composite components. This is yet a third variant that on the first glance looks a lot like custom tags, but these things are technically different as they aren't merely an include but represent true components with declared attributes, ability to attach validators to, etc.
I used to have one class for one file. For example car.cs has the class car. But as I program more classes, I would like to add them to the same file. For example car.cs has the class car and the door class, etc.
My question is good for Java, C#, PHP or any other programming language. Should I try not having multiple classes in the same file or is it ok?
I think you should try to keep your code to 1 class per file.
I suggest this because it will be easier to find your class later. Also, it will work better with your source control system (if a file changes, then you know that a particular class has changed).
The only time I think it's correct to use more than one class per file is when you are using internal classes... but internal classes are inside another class, and thus can be left inside the same file. The inner classes roles are strongly related to the outer classes, so placing them in the same file is fine.
In Java, one public class per file is the way the language works. A group of Java files can be collected into a package.
In Python, however, files are "modules", and typically have a number of closely related classes. A Python package is a directory, just like a Java package.
This gives Python an extra level of grouping between class and package.
There is no one right answer that is language-agnostic. It varies with the language.
One class per file is a good rule, but it's appropriate to make some exceptions. For instance, if I'm working in a project where most classes have associated collection types, often I'll keep the class and its collection in the same file, e.g.:
public class Customer { /* whatever */ }
public class CustomerCollection : List<Customer> { /* whatever */ }
The best rule of thumb is to keep one class per file except when that starts to make things harder rather than easier. Since Visual Studio's Find in Files is so effective, you probably won't have to spend much time looking through the file structure anyway.
No I don't think it's an entirely bad practice. What I mean by that is in general it's best to have a separate file per class, but there are definitely good exception cases where it's better to have a bunch of classes in one file. A good example of this is a group of Exception classes, if you have a few dozen of these for a given group does it really make sense to have separate a separate file for each two liner class? I would argue not. In this case having a group of exceptions in one class is much less cumbersome and simple IMHO.
I've found that whenever I try to combine multiple types into a single file, I always end going back and separating them simply because it makes them easier to find. Whenever I combine, there is always ultimately a moment where I'm trying to figure out wtf I defined type x.
So now, my personal rule is that each individual type (except maybe for child classes, by which a mean a class inside a class, not an inherited class) gets its own file.
Since your IDE Provides you with a "Navigate to" functionality and you have some control over namespacing within your classes then the below benefits of having multiple classes within the same file are quite worth it for me.
Parent - Child Classes
In many cases i find it quite helpful to have Inherited classes within their Base Class file.
It's quite easy then to see which properties and methods your child class inherits and the file provides a faster overview of the overall functionality.
Public: Small - Helper - DTO Classes
When you need several plain and small classes for a specific functionality i find it quite redundant to have a file with all the references and includes for just a 4-8 Liner class.....
Code navigation is also easier just scrolling over one file instead of switching between 10 files...Its also easier to refactor when you have to edit just one reference instead of 10.....
Overall breaking the Iron rule of 1 class per file provides some extra freedom to organize your code.
What happens then, really depends on your IDE, Language,Team Communication and Organizing Skills.
But if you want that freedom why sacrifice it for an iron rule?
The rule I always go by is to have one main class in a file with the same name. I may or may not include helper classes in that file depending on how tightly they're coupled with the file's main class. Are the support classes standalone, or are they useful on their own? For example, if a method in a class needs a special comparison for sorting some objects, it doesn't bother me a bit to bundle the comparison functor class into the same file as the method that uses it. I wouldn't expect to use it elsewhere and it doesn't make sense for it to be on its own.
If you are working on a team, keeping classes in separate files make it easier to control the source and reduces chances of conflicts (multiple developers changing the same file at the same time). I think it makes it easier to find the code you are looking for as well.
It can be bad from the perspective of future development and maintainability. It is much easier to remember where the Car class is if you have a Car.cs class. Where would you look for the Widget class if Widget.cs does not exist? Is it a car widget? Is it an engine widget? Oh maybe it's a bagel widget.
The only time I consider file locations is when I have to create new classes. Otherwise I never navigate by file structure. I Use "go to class" or "go to definition".
I know this is somewhat of a training issue; freeing yourself from the physical file structure of projects requires practice. It's very rewarding though ;)
If it feels good to put them in the same file, be my guest. Cant do that with public classes in java though ;)
You should refrain from doing so, unless you have a good reason.
One file with several small related classes can be more readable than several files.
For example, when using 'case classes', to simulate union types, there is a strong relationship between each class.
Using the same file for multiple classes has the advantage of grouping them together visually for the reader.
In your case, a car and a door do not seem related at all, and finding the door class in the car.cs file would be unexpected, so don't.
As a rule of thumb, one class/one file is the way to go. I often keep several interface definitions in one file, though. Several classes in one file? Only if they are very closely related somehow, and very small (< 5 methods and members)
As is true so much of the time in programming, it depends greatly on the situation.
For instance, what is the cohesiveness of the classes in question? Are they tightly coupled? Are they completely orthogonal? Are they related in functionality?
It would not be out of line for a web framework to supply a general purpose widgets.whatever file containing BaseWidget, TextWidget, CharWidget, etc.
A user of the framework would not be out of line in defining a more_widgets file to contain the additional widgets they derive from the framework widgets for their specific domain space.
When the classes are orthogonal, and have nothing to do with each other, the grouping into a single file would indeed be artificial. Assume an application to manage a robotic factory that builds cars. A file called parts containing CarParts and RobotParts would be senseless... there is not likely to be much of a relation between the ordering of spare parts for maintenance and the parts that the factory manufactures. Such a joining would add no information or knowledge about the system you are designing.
Perhaps the best rule of thumb is don't constrain your choices by a rule of thumb. Rules of thumb are created for a first cut analysis, or to constrain the choices of those who are not capable of making good choices. I think most programmers would like to believe they are capable of making good decisions.
The Smalltalk answer is: you should not have files (for programming). They make versioning and navigation painful.
One class per file is simpler to maintain and much more clear for anyone else looking at your code. It is also mandatory, or very restricted in some languages.
In Java for instance, you cannot create multiple top level classes per file, they have to be in separate files where the classname and filename are the same.
(C#) Another exception (to one file per class) I'm thinking of is having List in the same file as MyClass. Where I envisage using this is in reporting. Having an extra file just for the List seems a bit excessive.
Which naming convention do you use and why?
I like to use employeeNameTextBox, because:
It seems more natural from an English language perspective.
I find it's easier to look up with Intellisense.
The convention is similar to the convention used for events (MouseClickEvent, MouseClickEventHandler) and dependency properties (VisiblityProperty).
Note: I am using the full name rather than an abbreviation (such as "tb"), because it is in line with MS's naming conventions that say to avoid using abbreviations.
http://msdn.microsoft.com/en-us/library/ms229045.aspx
The only reason to use the control type in the name first (textBoxEmployeeName) is for easier grouping with Intellisense (All textbox controls would then show up together). Beyond that, there really is no benefit to using that way. I find the second way (employeeNameTextBox) more readable and prefer that way personally, but a lot of people will still go with the control type first, since that is the way it was done for a long time.
Naming your variables is so important. Thick client view conventions seem to be given the short end of the stick. Here are my thoughts:
Never put getters and setters for actual business values on your view. Don't do this:
public Name EmployeeName { get; set; }
To get or set an EmployeeName, your stateful code should explicitly call a method. Do it this way because it projects that the state is not stored on the view, but can be derived from or transposed to the view:
public void SetEmployeeName(Name employeeName);
public Name GetEmployeeName();
Hungarian notation is stupid. It was useful in languages <= VB6 because they used late binding of variable types. You had to protect yourself because type mismatches were runtime errors, not compile time. Only use txtEmployeeName if you also would use strEmployeeName and intEmployeeNumber.
If prefixing the pattern name isn't consistent with your naming convention, don't do it for the control type (which represents a pattern). If you wouldn't create a commandNameFormatting (instead of nameFormattingComamnd), then don't create a textBoxEmployeeName.
You'll probably need a suffix of some sort, since EmployeeName doesn't sufficiently describe the variable's purpose. An EmployeeName text box's purpose is to receive input. You could call it EmployeeNameTextBox if that makes you comfortable, but it might be better to call it EmployeNameInput. This has the added bonus that if you have a label, it's clear that EmployeeNamePrompt (or EmployeeNameLabel) is not the same as the text box. Without some sort of descriptive suffix, you don't have a good way to differentiate.
I (almost) always use [controltype][descriptive name]. I want to know right away what type of control I'm dealing with when I look at code, and if I DON'T remember the name, intellisense can help me out.
Just using a descriptive name (EmplyeeName) doesn't work for me. What type of control? Is it a label, a text box, or a combo box? Or a string? Or a file? It's important enough that the type of control or variable is always a part of it.
I propose a third option: uiEmployeName. Reasons:
It's not Hungarian. Both of the notations you mention are just flavors of Hungarian.
If you change an employee name text box over to a listbox you don't need to rename your variables.
Everything is grouped nicely in the intellisense without involving the type of the object.
The name of the object closely follows its function. It is a user-facing object that gets the employee name.
I generally try to keep the element type short, followed by a distinguishing label. I find that it quickly communicates the type and purpose of the element:
txtEmployeeName;
lblEmployeeName;
Why not EmployeeName? Seriously how does the control type as part of the name when it is already provided by your IDE assist in delivering easy to maintain code? Consider Ottenger's Rules for Variable and class Naming
K
As I read it, an article linked to in the article mentioned in the question (namely, Names of Resources) does use the control type at the end, in FileMenu (and ArgumentException though it's not a control).
My personal opinion is that this is also more readable, as it's the employee name text box and hence should be named the employeeNameTextBox, just like the words "File menu" are read in that order. (Though I substitute "Edit" for "TextBox" for brevity — I should probably kick that habit to use control names consistently with the environment name for them.)
A MUST READ is the XAML Guidelines released by Jaime:
Also read more here
WPF-specific Answer: No name at all.
Why? Because if you're developing using WPF you should not be naming your controls. If you are, you are doing something wrong.
WinForms required controls to be named because its data binding was so weak. WPF solves all that: The control itself can specify its data and behavior, so there is no need to name it.
I guess it's better to follow Microsoft's Object Naming Convention for naming your controls both in C# as well as Visual Basic.
I don't recommend hungarian notation in any form. textBoxEmployeeName is a form of hungarian notation. So I support the use of employeeNameTextBox.
Personally I don't even bother using the word TextBox, because it is not what is important about the variable. What is important is "Employee" and "Name". Not only does adding the word TextBox lock you in to a certain type, it also make it much harder to change that type, because you need to change the name to normalize your code and make it correct. Say for some reason you started this as a TextBox, but you later received a requirement to change this to a DropDownList or some other type, now you have to update all of your code and JavaScript to make it say DropDownList instead of TextBox.
It is much easier to forget about trying to type your variable names, and just simply name them. You have intellisense and compile time error checking for a reason, why not use it.
I would go with [controlType][DomainTerm] which in this case is textBoxEmployeeName. The reason is that while coding for the C# code behind you are more care about the UI controls than the domain specific terms.UI(View) side coding we need to identify/recognize the control type faster, which is little more important than the domain specific name in the View side , and since we read from 'Left to right' this naming convention is relevant.
I generally use txtEmployeeName or cmpEmployeeType , but textBox instead of txt is preferred as per MS guidelines
I have used both txtEmployeeName and employeeNameTextbox. Like many of the posts indicated, this is helpful for grouping. One groups by control types (txtEmployeeName, txtManagerName) while the other can group different related controls together (employeeNameTextbox, employeePhoneTextbox, managerNameTextBox, managerPhoneTextbox). In many cases I find the later more useful while coding.
You should do whatever it is that makes your code readable and self-documenting. Following hard and fast rules is always a mistake because they almost never cover all aspects of what needs to be done. There is nothing wrong with having guidelines (such as not using Hungarian notation), but it is more important that you are consistent and clear with your naming convention, whatever it is, than you follow some rules found on the Internet.
Ideas:
Avoid encodings/abbreviations.
The name should stand out from
similar names in the same scope.
Make the unique-most part the
left-most part. I suspect you have
several text boxes, but only one is
the employee name.
Avoid needless context. Are all the
names on this page about employees?
Is it an "employee" page? Then
EmployeeName is redundant. NameBox
or NameControl should be plenty.
Avoid needless context: do you have
names that are not controls? If so,
"Box", or "Control" is useful,
otherwise not so much.
Disclosure: I am the "ottinger" from "ottingers naming rules", which also evolved to be chapter 2 of "Clean Code". See short form at http://agileinaflash.blogspot.com/2009/02/meaningful-names.html
In VB I actually like to go with [ControlName]_[ControlType]. I can't remember how I started doing that but I suppose it's because it feels like a logical order. It also simplifies coding a bit because the code suggestions are grouped by the control description rather than the control type.
I name controls the same way in C# except I follow C#'s preference for camelCase: [controlName]_[controlType].
I also tend to use my own abbreviations for control types, though they are not vague.
Examples:
VB: Save_Btn and NewFile_MItem (menu item)
C#: save_btn and newFile_mItem
It works for me, but of course every programmer has their style.