Related
My friends and I were thinking of starting our own wiki. Given how widespread they have become recently, we heard it isn't that hard. We want to keep the site as simple as possible - we have some experience with web design, but not a whole lot with system administration. What are some things that we should keep in mind going forward (such as, which wikifarms may be useful, or what caveats should we keep in mind)?
I'm guessing from your question that you mean for personal, instead of business, use.
As Bayard implies, the key to success is the social side. For the technical side you'll need to have a server (or someone prepared to host it) and good wiki software. The most obvious choice here is MediaWiki which is well developed (features), well tested, well known (through Wikipedia) and completely free. Furthermore, it can easily be extended with a variety of new features (extensions).
Take your time making the choice of software because it is hard to change later. WikiMatrix may help here (to compare software).
However, the social side is also important. What is your topic? Why is it necessary? Could you accomplish the same with Google Docs (if it is just for friends) or do you want a wider involvement?
If you want a wider involvement (e.g. allow the public to contribute), then decide whether you will permit anonymous edits.
Now the most important: moderation. This means (1) you need clear rules (like who can delete pages and what the process is) and (2) someone (or, better, a group) to enforce those rules (the moderators). You will need to create the right balance for you in terms of being strict with the rules (encourages quality) and being flexible (encourages participation).
You will also need someone to take a lead - to encourage, support and manage the moderators and processes. This person is often called a wiki champion. Here's a good link explaining more about this role.
Final tips: be clear what should go onto the wiki and what not, stay close to your users (customers) by encouraging feedback and keep it fun for everyone!
Later addition: check out these Stack Overflow questions and answers:
Getting developers to use a wiki
Getting started with a personal wiki and moinmoin
Does it make sense to set up a wiki at the workplace?
What’s the best open source wiki platform?
Another edition: make sure the moderators create and maintain great "how to" pages for the wiki. Often they are not intuitive (especially for people used to Word). You might want to start with a "What is a wiki?" page - and then, after a brief introduction, link to a Wikipedia page all about wikis.
MindTouch has a free, open source wiki (http://www.mindtouch.com/downloads) that sounds like it would be perfect for what you're trying to do. I've used it in the past and it's super easy to get up and running and very flexible. Watch one of their demos before you make any decisions though (http://www.mindtouch.com/support_and_services/demo_videos).
The most difficult part of implementing a successful wiki tends to be social, rather than technical. Wikipatterns is a good resource which describes the challenges you're likely to encounter.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 6 years ago.
Improve this question
C++ has several types of styles: MFC, Boost, Google, etc. I would like to examine these styles and determine which one is best for my projects, but I want to read from the official style guidebook. Does anyone have an official guide that they typically use?
Here are two that I found. I bet there are more:
http://google-styleguide.googlecode.com/svn/trunk/cppguide.html
http://www.boost.org/development/requirements.html
Note: This is NOT a discussion about which style is best... only a call for official style guides that people currently use. Please refrain from bashing other style guides that you don't like.
Side question: Is there a good tool that can examine source code and tell if it matches a given style guide?
Not a Coding Guideline per se, but I find this mighty useful: Bjarne Stroustrup's C++ Style and Technique FAQ
There's no such thing as an "official" style guide - the C++ standard is entirely silent on style. One book on the subject by two highly knowledgable C++ guys is C++ Coding Standards by Sutter & Alexandrescu.
Other answers state that there is no official style guide, which was true at the time.
But in 2015, Bjarne Stroustrup announced the C++ Core Guidelines, an open source project to build authoritative guidelines for modern C++ code, led by Stroustrup himself and published by the Standard C++ Foundation:
http://github.com/isocpp/CppCoreGuidelines
In relevance to this question, the Core Guidelines also link to other guidelines, with added comments. About the often recommended Google C++ Style Guide, they say:
Geared toward C++03 and (also) older code bases. Google experts are now actively collaborating here on helping to improve these Guidelines, and hopefully to merge efforts so these can be a modern common set they could also recommend.
I have also written some tips for good coding in c++:
http://www.ivanism.com/Articles/CodingStandards.html
The post starts with:
The goal of coding standards are to increase the business value of the code. The most obvious (and indeed most important) way to do this is to make the code robust and low defect. Equally important, but more subtle goals include reducing coder friction and maintainability. As such, standards should be kept minimal -- simple enough to actually follow, and important enough to remember.
These standards should be used when building new source files. When an existing file needs to be changed, that is an appropriate time to bring it up to standard. However, it's never a good time to edit a file merely to bring it up to standard. If it ain't broke, don't "fix it" and remember to always "Keep it Working".
You'll notice that I don't touch on the classic "Religious" points:
tabs vs. spaces
indentation style
curly brace style
etc...
Consistency within a file is important and improves readability. But allowing coders to express themselves is also important. So, if you edit a file, either conform to the religion of that file, or convert the whole file to a new, consistent format. If you convert the whole file, you are effectively taking ownership of it, so be prepared to be the go-to person, or leave it as is.
C++ doesn't have and doesn't need an official style. Many organisations impose style guides on their contributors to try to maintain some kind of corporate look and feel; some of these contain snippets of good advice, but many just force you to add strange decorations that seemed like a good idea to someone writing a completely different language in the 1980s.
The only really useful advice you'll find amongst the waffle is:
Define a consistent way to distinguish types, objects, and some kinds of function (such as accessors and factories), so you'll know to write (for example) Thing thing = GetThing(); without looking the names up.
Don't start names with underscores. This is forbidden in some circumstances, and it's simpler and more readable to not do it at all than to worry about exactly when you can.
Spare a thought for the poor chap (perhaps you) who has to read and maintain the code in a few years' time.
Keep it simple.
Use your brain.
Another style guide are the The JSF air vehicle C++ coding standards.
I use my own style, which I have written up here. Whether or not you are interested in it as a style, if you're looking at styles in general you may find my discussion on the motivation for it to be useful.
To the side question: I don't personally know of any tools that analyze the style in use, but there are tools that reformat source to a given style guide. One that comes to mind is Artistic Style.
As for the side question, what you need is a static analysis tool. An expensive and huge tool is Klocwork. I've used it at a couple of shops and it can be set up to issue warnings against style issues. I don't recommend it for single users; it is more for a corporate environment. Although they may have stripped down versions for individuals.
Remember to Google for static analysis tools.
What are the technical questions I simply must have answers for before I approach someone about introducing a new language?
I'm looking for the list of technical questions that without a really good answer, I should not even waste anyone's time by proposing that we use language X.
PS: (def X clojure)
A crash course in politics for engineers...
Despite all the mission-statement baloney meant to sound noble and emphasize community support, the real purpose of every business is return on investment or, equivalently, maximizing shareholder value. If it's a government agency, it's kind of still the same question but the legal owners will have no direct influence and instead you will have proxy owners, such as higher agencies or powerful individual officials.
Decisions, however, are almost always made by agents, and so the principal-agent problem (also called the agency dilemma) appears; the agents (the management) will make a decision in their interest, and not necessarily according to the shareholder's interest as is theoretically required. In a government agency this is almost 100% of the consideration.
Sadly, this stirs in all the Dilbert and Parkinson's Law complexities.
The best you can conclude is that decisions will be justified on the basis of risk, cost, and benefit, but will tend to be made on the basis of what credit and blame is in store for the agent and understood by the agent, which is a narrow risk consideration of questionable value to the principal but at least an identifiable one.
So, we should now apply this to the language question. Your manager is likely to avoid threats, risks, scandals, and controversies. His application of the principals's concerns will be mainly through the constraints of budgets and expectations. Here are some examples that should be mostly self-explanatory.
If you want to use Java or PHP:
Everyone is doing it this way
This is the industry-standard approach for this type of problem
This is the low-risk approach
Similar systems have been done many times in Java/PHP
(That's the "no one ever got fired for buying IBM" argument.)
If you want to use Ruby:
Ruby is in the Tiobe top-ten (not quite an industry standard, so this is the best you can do)
PHP and Java are higher-cost technologies (he probably has a budget as an attempt to mitigate the principal-agent problem)
PHP and Java are going to be out of fashion "soon" (maybe not, but phrased as a "risk of appearing to stupidly use old tech', and implying the lack of later credit and recognition)
Ruby is an advanced language with powerful abstractions for cost-effective development (a weak argument for the agent, but offers the possibility of credit. The least effective of all the arguments.)
If you want to use Clojure:
You better prototype the system on weekends and evenings and present it as a solved problem.
Emphasize parallel Java / Clojure development ("if necessary the entire system can be written in Clojure Java")
Make all the Java arguments and then say something about "the best of both worlds"
Productivity with a language is neither the only factor, nor a simple scalar in itself. Important questions include:
How easy is it to learn the language, if it's not already familiar to people on the team?
How easy is it to become expert at the language?
Does the team have access to one or more language experts who have the bandwidth to do the necessary mentoring?
Are good learning materials (books, blogs, tutorials) and support channels (fora, IRC, mailing lists) available?
Does the language (or some framework in that language) allow a competent programmer to write the software faster than what you're using now?
How maintainable is the language? How readable is the syntax to a competent programmer encountering someone else's code for the first time? (Think of APL and Perl.)
Is the language somehow better applicable to your problem domain than what you're using now (e.g., functional languages for distributed computing)?
How well does the language/platform meet business needs not related to development speed (e.g., performance, scalability)?
What are the available tools like, and what do they cost? Is there a debugger available? An IDE? Refactoring and unit test support built into the IDE? Build management and deployment tools?
So much depends on what you're currently using, what you're switching to and why that it's difficult to answer. But these are always important:
What can I do if I choose a new language that I could not do before?
What could I do faster than I can currently with the new language?
How will the rest of the team cope with the introduction of the new language?
If I left, could someone else new to the language pick up where I left off without too many problems?
What is the business case?
It comes down to ROI (Return On Investment).
It is not only about an individual's productivity but:
the whole team
impact on product lifecycle
maintainability
etc.
How easy is it to pick up? I find this is not that important.
Does it have IDE support? Pretty important, but you can work without it.
Is there a debugger available? I think this is the most important question I would ask. Once you have a working debugger, you can usually get anything done.
We hired a team this year and decided to use Clojure as our weapon of choice. The team's background was primarily Java-based but also a wide variety of other languages for hobby work.
The criteria we considered were:
Can we leverage the Java/JVM background of the team and integrate with an existing Java-based product?
Can we achieve performance on par with Java?
Can we build thread-safe concurrent maintainable programs?
Can we leverage a higher level of abstraction
Can we hire/train people to work in the language?
Can we maintain a large codebase in the language?
Are sufficient tools available to work effectively in the language?
Is there an active community of people growing the language and libs?
We seriously considered Groovy, Scala, and Clojure. I really enjoy Groovy for lightweight apps but I had serious questions about performance. Scala and Clojure both have lots to offer on all of the points above. In the end, our problem domain involves a lot of symbolic manipulation and we felt that Clojure would be a better match but I suspect Scala also would work well.
What will your new language offer that an existing language doesn't already?
We have languages that do just about everything in every way today. So before introducing a new language, make sure there isn't one already existing that does everything your new language does. And make sure you know exactly what features your new language will offer that aren't offered in the same combination or at all by other languages.
Unless of course you're just doing this for your own education - in which case forget this question and have at it!
How will this improve my productivity?
If this cannot be answered pack up and go home.
What's the point? / Why?
How will it make my job easier?
Q1: Can I hire people with these skills?
Q2: When I call our outsourcing partner account managers, and ask how much would a typical fixed-cost project cost, if done in the usual way, or done using language X, is the multiplier more than 1?
Q3: Does everyone else in my department also have a favorite language that does about the same job as my favorite language, and should their favorite languages be used as well? What are the practical consequences of this?
A good question to ask is what is the size of the community around the language/framework. For instance, ruby/rails has a significant community around it, which would make me more comfortable that I would not be "the first kid on the block" to have to deal with a particular problem.
Why limit yourself to one language? Figure out which problems are solved best by which language and offer up services. If the bandwidth between the services is too high, then migrate the problematic services together based on which language solves both best.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
When in school it was often a requirement to flowchart the little programs that we wrote line for line.
Those flow charts tended, due to the size of the pictures, to be very large and were often tedious to draw.
It was always to such detail that you were essentially writing code anyway.
I use flowchart/UML style techniques to develop higher level things but when it gets down to actual loops and what not it seems like overkill.
I will often pseudo-code more detailed algorithms but still not to the super fine grained point.
Is this just one of those things where in school things were so tiny there would be nothing else to 'Flow-Chart' so they had use do the minutia?
Flowcharts, no -- Sequence diagrams, yes. I try to keep them at a very high-level to communicate the idea to someone quickly. I do not try to get every detail in. I might supplement with another diagram to show an edge case, if it seems important.
It's great for communication as a sketch -- I think it's not right for a specification (but would be a good intro to a detailed section)
Flow charts for the ifs and whiles of real code, never (in 30 years) found useful.
As a discussion aid for elicitng requirements ... so when we're here, what could happen? ... how would you decide ... what would you do if it's > 95% ... Can be helpful. A certain kin d of user finds such diagrams on the whiteboard easy to talk about.
To be absolutely honest, I am extremely glad I was required to accompany any assignment with flowcharts. They made me think structurally, something I was lacking (and, perhaps, still lacking to a certain extent).
So don't be quick to jump on a "I'm off to play the grand piano" bandwagon, flowcharts really do work.
Not once did I find myself in a bit of a bind in non-trivial logic. After laying out the logic in the flowchart form on a sheet of paper (takes a couple of minutes), it all inevitably becomes clear to me.
Yeah, I agree. The point was to get you to understand flow charts, not to imply that you should use them for line-by-line code coverage.
I don't know why you'd even waste time with pseudo-code except for demonstration, honestly, unless it's some really low-level programming.
I don't use them myself. But a coworker who only programs every once in a while does. It's a very handy way for him to remember the nuts-and-bolts of that program he wrote a year ago. He doesn't do much programming, so it's not worth it for him to learn sequence diagrams and things like that.
It's also the type of diagram that other pple that hardly ever program will be able to read easily. Which in his position is a plus.
I don't find great detail in a flowchart to be very helpful. I use UML-style techniques on a sheet of paper. Use a whiteboard in a group setting. Mid-level class diagrams and sequence diagrams can be extremely helpful to organize your ideas and communicate your design intentions.
Sometimes on a whiteboard to describe a process, but never in actual design or documentation. I'd describe them more as "flowchart-like" since I'm not always particular about the shapes.
We have an in-house application that has some fairly complex workflow in it. A flowchart forms a big part of the spec of this part of the system. So yes, Flowcharts are a useful tool for spec'ing a system. They are also normally understood by non-technical people which is useful if they are part of a user requirements. No, I would not normally use them at a very low level, nor would I expect part of a system to only be spec'ed or documented by flowcharts.
TDD is a good option for nuts and bolts code, if you are so inclined, and it comes with a lot of other benefits.
We have a large organically grown application that has very little documentation, so using flow charts to document components within the application has proven very usefull to the business side of the operation, as even they don't understand how everything fits together.
They aren't at line by line level, but do cover all branches of business logic with the subsequent processing and outputs (although not following strict flow chart rules - some blocks describe multiple processes).
I would like to know if there are any templates for doing this in a clear and concise way to give the gist of the application and its inner workings and how it meets the business needs. I do not want to write a mythological story so looking for any new ways of doing this.
Mostly this is about documenting what you actually need from the system. You can't make a good choice if you don't know what you need.
Here is a doc-style approach.
This is a decision matrix approach outline. The formatting is rough, but this is a good approach. This one has better formatting, but is not about software (it doesn't really matter).
I'm not exactly sure if this is what you are asking for, but check out this paper. It's a sample implementation of the CMMI's "Decision and Analysis Resolution" process area. It basically documents a method for comparing alternatives, reaching a decision, and documenting that decision.
The SEI's site has the original definition of DAR (see page 181), as well as a pretty good presentation about it. You have to realize that their whole goal is to help companies define their processes, not to push a particular process. So the documents you find there tend to be pretty high level, discussing the goals that your process should achieve and the specific practices that should be covered.
Consult Eric Evans' "Domain Driven Design". At the end of the day, you're going to have to use your experience and judgment - and that of your team - to make the design decisions big and small, but Evans recommends formulating a one-page manifesto, written in business terms, to share with biz types that explains the value of your view of the domain to the business.