This page shows the source for this entry, with WebCore formatting language tags and attributes highlighted.
Title
C# Handbook Rewrite
Description
Encodo published its first C# Handbook and published it to <a href="http://encodo.com/en/blogs.php?entry_id=141">its web site</a> in 2008. At the time, we also published to several other standard places and got some good, positive feedback. Over the next year, I made some more changes and published new versions. The latest version is 1.5.2 and is available from <a href="http://encodo.com/en/documents.php#csharp-handbook">Encodo's web site</a>. Since then, though I've made a few extra notes and corrected a few errors, but never published an official version again.
This is not because Encodo hasn't improved or modernized its coding guidelines, but because of several issues, listed below.
<ul>
At 72 pages, it's really quite long
A more compact, look-up reference would be nice
It contains a mix of C#-specific, Encodo-specific and library-specific advice
It's maintained in Microsoft Word
Code samples are manually formatted
New versions are simply new copies in versioned folders (no source control)
Collaboration is nearly impossible
There is nothing about any .NET version newer than 3.5
There is no mention of any other programming language (e.g. TypeScript, JavaScript)
A lot of stuff is overly complicated (e.g. <c>var</c> advice) or just plain wrong (e.g. <c>var</c> advice)
</ul>
To address these issues and to accommodate the new requirements, here's what we're going to do:
<ul>
Convert the entire document from Word to Markdown and put it in a Git repository<ul>
Collaboration? Pull requests. Branches.
Versioning? Standard diffing of commits.
Code samples? Automatic highlighting from GitLab (Encodo's internal server) or GitHub (external repository).
</ul>
Separate the chapters into individual files and keep them shorter and more focused on a single topic
Separate all of the advice and rules into the following piles:<ul>
General programming advice and best practices
C#-specific
Encodo-specific
Library-specific (e.g. Quino)
</ul>
</ul>
These are the requirements and goals for a new version of the C# handbook.
The immediate next steps are:
<ol>
Convert current version from Microsoft Word to Markdown (<del>done</del>)
Add everything to a Git repository (<del>done</del>)
Overhaul the manual to remove incorrect and outdated material; address issues above (<hl>in progress</hl>)
Mirror externally (<a href="https://github.com">GitHub</a> or <a href="https://gitlab.com">GitLab</a> or both)
</ol>
I hope to have an initial, modern version ready within the next month or so.