pegasus/anope
1
0
Fork 0
mirror of https://github.com/anope/anope.git synced 2026-07-05 17:43:13 +02:00
Code Activity

Remove some outdated development docs.

Browse Source
This commit is contained in:
Sadie Powell
2024-02-11 21:08:17 +00:00
parent 274bb19d03
commit c50d1dc2b5
5 changed files with 0 additions and 383 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ASTYLE
-1
View File
@@ -1 +0,0 @@
astyle --style=java --indent=tab --brackets=break-closing --indent-switches --indent-cases --brackets=break
docs/BUGS
-1
View File
@@ -1 +0,0 @@
For all bug reports / updates please see https://github.com/anope/anope/issues
docs/C++CASTING
-111
View File
@@ -1,111 +0,0 @@
C++-style Casting
=================
In C, you can cast in one of two ways:
(type)var
type(var)
The problem with C-style casting is that it allows a programmer to get away
with too much, and is also not designed to handle C++ classes.
C++ has 4 types of casting in addition to allowing C-style casting. They are:
static_cast
const_cast
dynamic_cast
reinterpret_cast
The syntax is usually *_cast<type>(var).
static_cast
-----------
From my experience, this cast is closest to C-style casting for non-pointer
types as well as between some (but not all) pointer types. This type of cast,
like C-style casting, is performed at compile-time. static_cast can also do
a downcast of a derived class to a base class, but only if the base class is
not a virtual base class. Sometimes the result of this cast can become
undefined. static_cast is a bit more strict that C-style casting, though. It
disallows certain class conversions that would've been allowed with a C-style
cast. static_cast also doesn't allow you to cast to an incomplete type. In
these cases, I would try either dynamic_cast or reinterpret_cast.
const_cast
----------
This cast is mainly to add or remove const-ness or volatile-ness from a
variable. This is safer than using a C-style cast to change the const-ness
of a variable. In most cases if you try to use one of the other casts and it
complains about const-ness, you will want to either use this cast instead or
wrap the other cast around this cast. An example:
const int *a;
static_cast<void *>(a); <-- This will fail.
To remedy the above, you would might try this:
const int *a;
const_cast<void *>(a); <-- But this will still fail.
The real solution is this:
const int *a;
static_cast<void *>(const_cast<int *>(a));
It is not recommended to use const_cast on the this variable within a member
function of a class that is declared const. Instead you should use the mutable
keyword on the variable in the class's definition.
dynamic_cast
------------
This cast can only be used on pointers or references to classes. It can cast a
derived class to a base class, a derived class to another derived class
(provided that both are children of the same base class), or a base class to a
derived class. You can also use this to cast a class to void *. This cast is
done at run-time as opposed to the other casts, and relies on C++'s RTTI to be
enabled. It is meant to be used on polymorphic classes, so use static_cast on
non-polymorphic classes.
derived-to-base conversions are actually done statically, so you use either
dynamic_cast or static_cast on them, regardless of if the classes are
polymorphic or not.
derived-to-derived or base-to-derived conversions, however, rely on run-time
type information, and this cast is used on those classes that are polymorphic.
This is safer than C-style casting in that an invalid pointer conversion will
return a NULL pointer, and an invalid reference conversion will throw a
Bad_cast exception.
Note that in Anope we prefer if Anope::debug_cast is used.
This uses dynamic_cast (and checks for a NULL pointer return) on debug builds
and static_cast on release builds, to speed up the program because of dynamic_cast's
reliance on RTTI.
reinterpret_cast
----------------
This cast I would use only as a last resort if static_cast isn't allowed on a
conversion. It allows for conversions between two unrelated types, such as
going from char * to int *. It can also be used to convert a pointer to an
integral type and vica versa. The sites I've read mention how the result is
non-portable, which I assume means the resulting object code is non-portable,
so since the code is compiled on many systems anyways, I don't see this as
being a huge issue. It is recommended to only use this if necessary, though.
Links
=====
The following links are web sites I've used to get this information, and might
describe some of the above a bit better than I have. :P
https://www.acm.org/crossroads/xrds3-1/ovp3-1.html
http://www.cplusplus.com/doc/tutorial/typecasting.html
http://www.codeguru.com/forum/showthread.php?t=312456
https://web.archive.org/web/20170810222238/http://www.cs.umd.edu/class/sum2003/cmsc311/Notes/BitOp/cast.html
https://www.microsoft.com/en-us/download/details.aspx?id=55984
https://en.wikibooks.org/wiki/C%2B%2B_Programming/Type_Casting
https://web.archive.org/web/20160510114447/http://www.informit.com/guides/content.aspx?g=cplusplus&seqNum=134
-- CyberBotX, Nov 23, 2008
docs/CODING
-239
View File
@@ -1,239 +0,0 @@
Originally pulled from: https://wiki.inspircd.org/Coding_Guidelines
---
InspIRCd Coding Guidelines
The following are a set of guidelines for writing patches to InspIRCd, or for
creating modules for distribution with the official package. These guidelines
were written a time after InspIRCd development started, and so not all code
yet follows these. This will be rectified with time.
1. Comments
* Multi Line
Multiple line comments should follow the C-style comment, for example:
/*
* This is a multiple line comment, huzzah..
*/
* Single Line
Single line comments should also be in the C style, for example:
/* This is a boring one-line comment */
* Doxygen commenting
If you wish your comment to show in doxygen, the comment should be directly
above the item you are documenting (a class, function, enum, etc) and the
first line should be "/**". For example:
/** This is a doxygen multiline comment.
* Description of thingymebob here.
*/
The first line after the "**" is used as the short description of the item
(up to the full stop) and everything afterwards as the detailed description.
2. Indentation
Tabs. Tabs. ONLY TABS. Use a single tab for each level of indentation,
for example:
int main()
{
<tab>if (condition)
<tab>{
<tab><tab>code
<tab>}
}
3. Separation
Always put a space in between a keyword like if/while and the condition,
for example:
if (foo == bar)
NOT
if(foo == bar)
4. Braces
Always put braces opening and closing blocks on separate lines, see the
indentation example. For example, place braces like this:
if (apples == "green")
{
cout << "Apples are green" << endl;
}
and not:
if (apples == "green") {
cout << "Apples are green" << endl;
}
The one exception to this is if you are declaring a class method which is
only one line long, in that case the following is acceptable in most cases:
class foo : public bar
{
foo() { }
getrandomfoo() { return rand(); }
};
5. Templates
Where possible, use templates rather than #defines. Avoid use of RTTI.
6. Structs
Structs should be declared in the following fashion:
struct BodyPartBasket
{
int arms;
int legs;
int scrotalsacs;
};
and not like this:
typedef struct
{
int arms;
int legs;
int scrotalsacs;
} BodyPartBasket;
The second way is not required in C++ to be able to do this:
BodyPartBasket mybasket;
Plus, placing the name at the bottom of the declaration makes readability
more difficult (as you have to scroll down to the bottom of the struct to
find its name). (where possible, call them classes rather than structs.)
7. Variable naming
Class and struct names should be in camel case with a leading capital letter,
for example "MyBagOfBones" and not "my_bag_of_bones" or "mybagofbones".
Variable names can be in either camel case with a leading capital letter or
alternatively all lower case, so long as the same naming convention is
adhered to throughout the class. No classes or variables should be named in
capitals unless this makes sense for the name (for example "class DNS").
Constants and enum values should always be completely in CAPITALS and
underscores may be used, for example:
enum DecayState
{
DECAYED_MOULDY = 0,
DECAYED_SMELLY = 1,
DECAYED_MAGGOTS = 2
};
All value names in an enum should be started with the same text which should
be related in some way to the enum's use. For example "DNS_CNAME, DNS_A,
DNS_AAAA".
8. Use of references
Wherever possible, when dealing with any complex class, pass a const reference
rather than a copy of the class. For example:
MyThingy::MyThingy(const std::string &thingyvalue)
{
}
Of course, if you intended to change the string you can just omit the 'const'.
9. Use of char pointers
Whenever you use char pointers (char*, char**) try to use const equivalents.
This is much safer and avoids ugly and dangerous casts. For example:
MyThingy::Thingify(const char* const* wotsits)
{
}
If it is possible without performance loss, consider avoiding char pointers
altogether and using std::string instead.
10. Use of STL
For more information on use of STL in InspIRCd, please see the separate
STL FAQ.
11. Making copies of data
Never ever make a copy of a piece of data unless it is absolutely necessary.
For example, don't use strlcpy() to make a copy of the const char* string
returned by std::string::c_str(), if the change can be done to the std::string
itself. The same goes for unnecessary variable assignments, especially those
which assign large classes.
12. namespace std
Avoid the following:
using namespace std;
It might take a bit more typing, but things work better if you don't set
(then later assume) the namespace -- specify it explicitly when you want to
use it.
13. Linefeeds
Unix linefeeds only please. We do not like to see our screens covered in ^M.
14. Portability
Always make sure your code is portable to all supported operating systems,
remember of course that as of 1.1.8 this includes windows. Don't write code
that only works on windows, or only works on Linux. Test your code on all
platforms or ask for help from other developers who have the platforms you
want to test on.
* new() and delete(), malloc() and free()
Apart from the fact that using malloc() and free() is bad practice in C++
code, you must never use malloc() or free() in InspIRCd, within its modules
or within the core. This is because if you use malloc() or free() in windows,
the memory is claimed from the program's local heap.
In windows, each shared object (module, dll) has its own heap, which is
protected from other dlls and executables. To get around this issue and
allow more posix-like memory access from other dlls in the program (other
modules), InspIRCd overrides the operators new and delete to ensure that
memory allocated by them comes from the windows global heap. If you use
malloc() and free() for this, the ircd will segfault when another module
tries to access the memory you have allocated!
* strdup()
As with malloc(), above, strdup() should be avoided. Where strdup() is
absolutely necessary, use strnewdup() which is our strdup() implementation
that calls operator new instead of using malloc().
char arrays allocated by strnewdup() should be deleted with operator delete[].
* CoreExport and DllImport
Prefix all types you want to import or export to other modules with CoreExport
and DllImport macros. These do nothing in POSIX operating systems, however
in windows these are expanded to the instructions __declspec(dllimport) and
__declspec(dllexport) respectively depending on where they are used and how.
15. External Dependencies
If a module is compiled as standard, or the code is part of the core, you must
not use any dependencies that are not available as standard on all supported
operating systems beyond libstdc++, libc, and whatever else is currently
required to build the core. Modules which use nonstandard dependencies belong
in the modules/extra directory.
16. Profiling and Performance
It is one thing to assume that code performs bad, it is another thing to prove
that it actually is. A lot of experienced programmers talk about 'premature
optimisation', and here is what it means: if you have a piece of code called
once on startup that takes 10 seconds instead of one second to run, and a
piece of code that takes 0.05 seconds to run when it should take 0.01, and
it is called once per second, the second piece of code is the priority.
In other words, make sure that what you think is slow, and a performance
problem in Insp actually is.
To do this, use the callgrind tool from Valgrind (valgrind --tool=cachegrind
bin/inspircd -nofork -debug), and kcachegrind (or similar) to view the output
files.
docs/EVENTS
-31
View File
@@ -1,31 +0,0 @@
Anope Internal Events
---------------------
1) Intro
2) Using Events
1) Introduction to Internal Events
Internal Events are setup to give module developers more information
about what the core is doing at different times. This information can
be as complex as data we are feeding to the uplink, to simple triggered
events such as the databases being saved.
Additionally there is a module included with the core
which can provide some clue as to how to use the code in your modules.
The rest of this document assumes that you are used to writing modules.
2) Using Events
Each Event in Anope calls a function.
You must override these functions in your main modules class.
The full list of functions and parameters are in modules.h. In this
case, you would be overriding OnJoinChannel() and OnPartChannel() like so:
void OnJoinChannel(User *u, Channel *c) override { }
void OnPartChannel(User *u, Channel *c) override { }
Some of these event overrides can be used to prevent or allow things to
happen that would normally not be allowed or denied. You can also use
ModuleManager (not explained here) to set control which order the modules
are queried (when multiple modules hook to the same event).