Difference between revisions of "Writing warning-free code"

From Apache OpenOffice Wiki
Jump to: navigation, search
m (fix link)
(→‎Name hiding)
Line 95: Line 95:
  
 
In C++, use a <code>using</code> declaration to make visible (virtual) function declarations from a base clase that would be hidden by a function declaration in a derived class:
 
In C++, use a <code>using</code> declaration to make visible (virtual) function declarations from a base clase that would be hidden by a function declaration in a derived class:
−
<blockquote><code>
+
<code>[cpp]
−
class Base {<br/>
+
class Base {
−
public:<br/>
+
public:
−
&emsp;virtual void f(int);<br/>
+
  virtual void f(int);
−
&emsp;virtual void f(double);<br/>
+
  virtual void f(double);
−
};<br/>
+
−
class Derived: public Base {<br/>
+
−
public:<br/>
+
−
&emsp;using Base::f;<br/>
+
−
&emsp;virtual void f(int);<br/>
+
 
};
 
};
−
</code></blockquote>
+
class Derived: public Base {
 +
public:
 +
  using Base::f;
 +
  virtual void f(int);
 +
};
 +
</code>
 +
 
 
Make sure to apply the correct access control to the <code>using</code> declaration:
 
Make sure to apply the correct access control to the <code>using</code> declaration:
−
<blockquote><code>
+
<code>[cpp]
−
class Base {<br/>
+
class Base {
−
protected:<br/>
+
protected:
−
&emsp;void f();<br/>
+
  void f();
−
};<br/>
+
};
−
class Derived: public Base {<br/>
+
class Derived: public Base {
−
public:<br/>
+
public:
−
&emsp;void f(int);<br/>
+
  void f(int);
−
protected:<br/>
+
protected:
−
&emsp;using Base::f;<br/>
+
  using Base::f;
 
};
 
};
−
</code></blockquote>
+
</code>
 +
 
 
If you can, avoid such constructs as in the above example, by chosing different names for the two functions <code>f</code>. If on the other hand the function f is clearly meant to be overloaded, then make all instances of <code>f</code> virtual in the base class.
 
If you can, avoid such constructs as in the above example, by chosing different names for the two functions <code>f</code>. If on the other hand the function f is clearly meant to be overloaded, then make all instances of <code>f</code> virtual in the base class.
  

Revision as of 14:53, 16 November 2005

On CWS warnings01 we are currently on the way towards a completely warning-free OOo C/C++ code base. And once we have reached that, we want to keep the code clean!

On that CWS, you currently need to build with the build switch werror=1 to turn compiler warnings into errors, as for example in

build werror=1

There is also a build switch wall=1 to switch on as many compiler warnings as usefull, but its effect is already switched on per default on the four Hamburg-relevant platforms unxlngi6, unxsoli4, unxsols4, and wntmsci10. In the future, the behaviour triggered by those switches may become default behaviour (on all platforms), so that the switches may no longer be necessary.

If your job is to clean up a given CVS module on that CWS, here are some practical guidelines:

  • Work directly on the CWS (/cws/cws03/warnings01 in Hamburg).
  • Make sure your module builds and delivers successfully with build werror=1 && deliver.
  • If your module contains external code which we do not want to clean up, set EXTERNAL_WARNINGS_NOT_ERRORS := TRUE at the beginning of the corresponding makefile.mk, so that warnings do not lead to errors there.
  • In any case, for any header file delivered from your module, make sure that testhxx on the delivered header file is successful.
  • If you encounter a warning that cannot reasonably be worked around, discuss that problem on dev@openoffice.org. One outcome of that discussion can be that we globally disable that particular warning. To see which warnings are already globally disabled on a given platform, look at the settings for CFLAGSWARNCC, CFLAGSWARNCXX, CFLAGSWALLCC, and/or CFLAGSWALLCXX in the platform-specific .mk file in solenv/inc (unxlngi6.mk, unxsoli4.mk, unxsols4.mk, and the "$(COMEX)"==10 branch of wnt.mk).
  • Commit your changes (do not forget to add your module to the CWS before making any changes).
  • In a first step, we concentrate on cleaning up the code for unxlngi6.pro. In a second step, the other Hamburg platforms (unxlngi6, unxsoli4.pro, unxsols4, unxsols4.pro, wntmsci10, and wntmsci10.pro) will follow.
  • Anounce in a mail to all people involved in the CWS that your module is cleaned up for unxlngi6.pro (or even more platforms).
  • /tausch/cl/warningfreecode.csv in Hamburg represents the current status. That document is updated by StephanBergmann from the anouncement mails; do not modify it yourself.

The following is a list of issues you might come across when making existing code warning-free, or when writing new, warning-free code:

Integral conversions

Sometimes, a cast between integral types is needed to avoid a warning. In such a case, use sal::static_int_cast (C++) or SAL_INT_CAST (C) to make that cast stick out—it will need to be adapted when the type of any of the involved expressions changes later on:

sal_Int32 n;
std::vector<char> v;
if (n >= 0 && sal::static_int_cast<sal_uInt32>(n) == v.size()) ...

Casting between pointer and integer types

!! C++

  • From pointer-to-(possibly-cv-qualified-)void-or-object type P to unsigned integral type U:

P p;
U u = sal::static_int_cast<U>(reinterpret_cast<sal_uIntPtr>(p));

  • From unsigned integral type U to pointer-to-(possibly-cv-qualified-)void-or-object type P:

U u;
P p = reinterpret_cast<P>(sal::static_int_cast<sal_uIntPtr>(u));

  • From pointer-to-(possibly-cv-qualified-)void-or-object type P to signed integral type S:

P p;
S s = sal::static_int_cast<S>(reinterpret_cast<sal_IntPtr>(p));

  • From signed integral type S to pointer-to-(possibly-cv-qualified-)void-or-object type P:

S s;
P p = reinterpret_cast<P>(sal::static_int_cast<sal_IntPtr>(s));

!! C

  • From pointer-to-(possibly-qualified-)void-or-object type P to unsigned integer type U:

P p;
U u = SAL_INT_CAST(U, (sal_uIntPtr) p);

  • From unsigned integer type U to pointer-to-(possibly-qualified-)void-or-object type P:

U u;
P p = (P) SAL_INT_CAST(sal_uIntPtr, u);

  • From pointer-to-(possibly-qualified-)void-or-object type P to signed integer type S:

P p;
S s = SAL_INT_CAST(S, (sal_IntPtr) p);

  • From signed integer type S to pointer-to-(possibly-qualified-)void-or-object type P:

S s;
P p = (P) SAL_INT_CAST(sal_IntPtr, s);

Pointer to function

A pointer to function is not compatible with a pointer to object, so code like

void * osl::Module::getSymbol(rtl::OUString const &);
typedef void (* !MyFunc)();
!MyFunc f = module.getSymbol("myFunc");

will not compile. The only places were converting between pointer to function and pointer to object (typically void *) should be necessary are osl::Module::getSymbol and osl::Module::getUrlFromAddress, and in both cases there are additional functions (osl::Module::getFunctionSymbol and an overload with oslGenericFunction of osl::Module::getUrlFromAddress) that handle the problem internally. Use them!

Name hiding

In C++, use a using declaration to make visible (virtual) function declarations from a base clase that would be hidden by a function declaration in a derived class: [cpp] class Base { public: 

 virtual void f(int);
 virtual void f(double);

}; class Derived: public Base { public: 

 using Base::f;
 virtual void f(int);

};

Make sure to apply the correct access control to the using declaration: [cpp] class Base { protected: 

 void f();

}; class Derived: public Base { public: 

 void f(int);

protected: 

 using Base::f;

};

If you can, avoid such constructs as in the above example, by chosing different names for the two functions f. If on the other hand the function f is clearly meant to be overloaded, then make all instances of f virtual in the base class.

Unused parameters

There are three cases where a parameter of a function is not actually used in the definition of the function:

  • The function has to have a certain signature (it is a virtual function, shall be used with a certain function pointer type, or is part of a stable API that cannot be changed). In those cases, leave out the paramter name in the function definition (C++) or use

(void) paramName; /* avoid warning about unused parameter */

at the start of the function body (C).

  • The function uses the paramter only in an #ifdef-block, or only in OSL_ASSERT etc. debug code. If the first case occurs in C++ code, fix it by using the same #ifdef around the parameter name in the function header. In all other cases, fix it by using

(void) paramName; /* avoid warning about unused parameter */

at the start of the function body.

  • The function once used the parameter, but does no longer do so. In that case, clean up the function declaration and all uses of the function.

When all else fails

There are cases where the only sensible solution is to suppress warnings for a given chunk of code:

  • As explained above, in external code which we do not want to clean up, use EXTERNAL_WARNINGS_NOT_ERRORS := TRUE so that warnings do not lead to errors there.
  • Header files included directly from the system, or header files delivered from external code included in the OOo code base but which we cannot reasonably make testhxx-clean: Surround that code (e.g., the #include-directives for those headers) by
  1. if defined __GNUC__
  2. pragma GCC system_header
  3. elif defined __SUNPRO_CC
  4. pragma disable_warn
  5. elif defined _MSC_VER
  6. pragma warning(push, 1)
  7. endif

and

  1. if defined __SUNPRO_CC
  2. pragma enable_warn
  3. elif defined _MSC_VER
  4. pragma warning(pop)
  5. endif

(probably together with an explanatory comment). Due to the nature of the GCC solution, this does not work directly within the compilation unit's main (.c, .cxx) file, only within a (.h, .hxx) file included directly or indirectly.

  • Code generated by flex or bison: The solution here is similar to the solution in the previous item—disable all warnings in the generated code. However, this has two implications: For one, it means that also all warnings from our client code integrated into the flex/bison output are suppressed; this is not really that large an issue, given the relatively small number of flex/bison files we use. For another, due to the nature of the GCC solution, it means that you need to introduce a wrapper file. The individual steps for a given flex/bison file named example.ly, translated to $(MISC)$/example.cxx, are as follows: First, change example.ly by adding
  1. if defined __GNUC__
  2. pragma GCC system_header
  3. elif defined __SUNPRO_CC
  4. pragma disable_warn
  5. elif defined _MSC_VER
  6. pragma warning(push, 1)
  7. endif

(probably together with an explanatory comment) at the top of the initial } section. Second, create a new file named wrap_example.cxx in the same source directory as exmaple.ly, containing

  1. include "example.cxx</var>"

Third, change the corresponding makefile.mk by adding

INCPRE=$(MISC)

to the top, by changing occurences of example.obj to wrap_example.obj, and by adding

$(OBJ)$/wrap_example.obj: $(MISC)$/example.cxx

and/or

$(SLO)$/wrap_example.obj: $(MISC)$/example.cxx

at the bottom.

Retrieved from "https://wiki.openoffice.org/w/index.php?title=Writing_warning-free_code&oldid=2030"
Personal tools